Yoctopuce Yocto-Display User manual

Yocto-Display
User Manual

www.yoctopuce.com III
Table of contents
1. Introduction 1...............................................................................................................................
1.1. Safety Information 2...............................................................................................................
1.2. Environmental conditions 2...................................................................................................
2. Presentation 3..............................................................................................................................
2.1. Common elements 3...............................................................................................................
2.2. Specific elements 4................................................................................................................
2.3. Optional accessories 5...........................................................................................................
3. Working principles 7................................................................................................................
3.1. Embedded processor and memory 7....................................................................................
3.2. Orientation 7............................................................................................................................
3.3. Layer system 7........................................................................................................................
3.4. Graphic routines 8..................................................................................................................
3.5. Text display 9..........................................................................................................................
3.6. Font file format 10...................................................................................................................
3.7. Sequences and animations 11...............................................................................................
3.8. Optimizations 11.....................................................................................................................
4. The embedded file system 13.............................................................................................
4.1. Usage 13..................................................................................................................................
4.2. Limitations 14..........................................................................................................................
5. First steps 15................................................................................................................................
5.1. Prerequisites 15......................................................................................................................
5.2. Testing USB connectivity 16..................................................................................................
5.3. Localization 17........................................................................................................................
5.4. Test of the module 17.............................................................................................................
5.5. Configuration 17.....................................................................................................................
6. Assembly and connections 19...........................................................................................
6.1. Fixing 19..................................................................................................................................
6.2. USB power distribution 19.....................................................................................................

IV www.yoctopuce.com
7. Programming, general concepts 21.................................................................................
7.1. Programming paradigm 21....................................................................................................
7.2. The Yocto-Display module 23................................................................................................
7.3. Module control interface 24...................................................................................................
7.4. Display function interface 25.................................................................................................
7.5. AnButton function interface 26.............................................................................................
7.6. Files function interface 27......................................................................................................
7.7. What interface: Native, DLL or Service ? 28.........................................................................
7.8. Programming, where to start? 30..........................................................................................
8. Using the Yocto-Display in command line 31............................................................
8.1. Installing 31.............................................................................................................................
8.2. Use: general description 31...................................................................................................
8.3. Control of the Display function 32........................................................................................
8.4. Control of the module part 32................................................................................................
8.5. Limitations 33..........................................................................................................................
9. Using Yocto-Display with JavaScript / EcmaScript 35..........................................
9.1. Blocking I/O versus Asynchronous I/O in JavaScript 35....................................................
9.2. Using Yoctopuce library for JavaScript / EcmaScript 2017 36...........................................
9.3. Control of the Display function 38........................................................................................
9.4. Control of the module part 42................................................................................................
9.5. Error handling 44....................................................................................................................
10. Using Yocto-Display with PHP 47..................................................................................
10.1. Getting ready 47....................................................................................................................
10.2. Control of the Display function 47......................................................................................
10.3. Control of the module part 49..............................................................................................
10.4. HTTP callback API and NAT filters 52.................................................................................
10.5. Error handling 55..................................................................................................................
11. Using Yocto-Display with C++ 57...................................................................................
11.1. Control of the Display function 57......................................................................................
11.2. Control of the module part 60..............................................................................................
11.3. Error handling 62..................................................................................................................
11.4. Integration variants for the C++ Yoctopuce library 63......................................................
12. Using Yocto-Display with Objective-C 65..................................................................
12.1. Control of the Display function 65......................................................................................
12.2. Control of the module part 67..............................................................................................
12.3. Error handling 69..................................................................................................................
13. Using Yocto-Display with Visual Basic .NET 71.....................................................
13.1. Installation 71........................................................................................................................
13.2. Using the Yoctopuce API in a Visual Basic project 71......................................................
13.3. Control of the Display function 72......................................................................................
13.4. Control of the module part 74..............................................................................................
13.5. Error handling 76..................................................................................................................
14. Using Yocto-Display with C# 79......................................................................................
14.1. Installation 79........................................................................................................................

www.yoctopuce.com V
14.2. Using the Yoctopuce API in a Visual C# project 79...........................................................
14.3. Control of the Display function 80......................................................................................
14.4. Control of the module part 82..............................................................................................
14.5. Error handling 85..................................................................................................................
15. Using the Yocto-Display with Universal Windows Platform 87.....................
15.1. Blocking and asynchronous functions 87..........................................................................
15.2. Installation 88........................................................................................................................
15.3. Using the Yoctopuce API in a Visual Studio project 88....................................................
15.4. Control of the Display function 89......................................................................................
15.5. A real example 89.................................................................................................................
15.6. Control of the module part 91..............................................................................................
15.7. Error handling 93..................................................................................................................
16. Using Yocto-Display with Delphi 95..............................................................................
16.1. Preparation 95.......................................................................................................................
16.2. Control of the Display function 95......................................................................................
16.3. Control of the module part 97..............................................................................................
16.4. Error handling 100................................................................................................................
17. Using the Yocto-Display with Python 101.................................................................
17.1. Source files 101....................................................................................................................
17.2. Dynamic library 101..............................................................................................................
17.3. Control of the Display function 101....................................................................................
17.4. Control of the module part 104............................................................................................
17.5. Error handling 105................................................................................................................
18. Using the Yocto-Display with Java 107.......................................................................
18.1. Getting ready 107..................................................................................................................
18.2. Control of the Display function 107....................................................................................
18.3. Control of the module part 110............................................................................................
18.4. Error handling 112................................................................................................................
19. Using the Yocto-Display with Android 113...............................................................
19.1. Native access and VirtualHub 113.......................................................................................
19.2. Getting ready 113..................................................................................................................
19.3. Compatibility 113..................................................................................................................
19.4. Activating the USB port under Android 114.......................................................................
19.5. Control of the Display function 116....................................................................................
19.6. Control of the module part 118............................................................................................
19.7. Error handling 123................................................................................................................
20. Advanced programming 125.............................................................................................
20.1. Event programming 125.......................................................................................................
21. Using with unsupported languages 127.....................................................................
21.1. Command line 127................................................................................................................
21.2. VirtualHub and HTTP GET 127.............................................................................................
21.3. Using dynamic libraries 129................................................................................................
21.4. Porting the high level library 132........................................................................................
22. High-level API Reference 133...........................................................................................

VI www.yoctopuce.com
22.1. General functions 134..........................................................................................................
22.2. Module control interface 169...............................................................................................
22.3. Display function interface 235.............................................................................................
22.4. DisplayLayer object interface 292.......................................................................................
22.5. AnButton function interface 324.........................................................................................
22.6. Files function interface 372..................................................................................................
23. Troubleshooting 413..............................................................................................................
23.1. Where to start? 413..............................................................................................................
23.2. Programming examples don't seem to work 413..............................................................
23.3. Linux and USB 413...............................................................................................................
23.4. ARM Platforms: HF and EL 414...........................................................................................
23.5. Powered module but invisible for the OS 414....................................................................
23.6. Another process named xxx is already using yAPI 414....................................................
23.7. Disconnections, erratic behavior 414.................................................................................
23.8. Damaged device 415............................................................................................................
24. Characteristics 417.................................................................................................................

1. Introduction
The Yocto-Display is a 66x58mm electronic module allowing you to drive a 128 x 32px monochrome
OLED screen, as well as 6 channels which can measure the state of switches, push buttons, or even
potentiometers. This screen enables you to easily display some easily readable pieces of information
from a machine which does not usually have a monitor.
The Yocto-Display module
The Yocto-Display is not in itself a complete product. It is a component intended to be integrated into
a solution used in laboratory equipments, or in industrial process-control equipments, or for similar
applications in domestic and commercial environments. In order to use it, you must at least install it
in a protective enclosure and connect it to a host computer.
Yoctopuce thanks you for buying this Yocto-Display 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-Display
is easy to install anywhere and easy to drive from a maximum of programming languages. If you are
nevertheless disappointed with this module, or if you need additional information, do not hesitate to
contact Yoctopuce support:
E-mail address: [email protected]
Web site: www.yoctopuce.com
Postal address: Chemin des Journaliers, 1
ZIP code, city: 1236 Cartigny
Country: Switzerland
www.yoctopuce.com 1

1.1. Safety Information
The Yocto-Display is designed to meet the requirements of IEC 61010-1:2010 safety standard. It
does not create any serious hazards to the operator and surrounding area, even in single fault
condition, as long as it is integrated and used according to the instructions contained in this
documentation, and in this section in particular.
Protective enclosure
The Yocto-Display should not be used without a protective enclosure, because of the accessible
bare electronic components. For optimal safety, it should be put into a non-metallic, non-inflammable
enclosure, resistant to a mechanical stress level of 5 J. For instance, use a polycarbonate (e.g.
LEXAN) enclosure rated IK08 with a IEC 60695-11-10 flammability rating of V-1 or better. Using a
lower quality enclosure may require specific warnings for the operator and/or compromise conformity
with the safety standard.
Maintenance
If a damage is observed on the electronic board or on the enclosure, it should be replaced in order to
ensure continued safety of the equipment, and to prevent damaging other parts of the system due to
overload that a short circuit could cause.
Identification
In order to ease the maintenance and the identification of risks during maintenance, you should
affixate the water-resistant identification label provided together with the electronic board as close as
possible to the device. If the device is put in a dedicated enclosure, the identification label should be
affixated on the outside of the enclosure.
Application
The safety standard applied is intended to cover laboratory equipment, industrial process-control
equipment and similar applications in residential or commercial environment. If you intend to use the
Yocto-Display for another kind of application, you should check the safety regulations according to
the standard applicable to your application.
In particular, the Yocto-Display is not certified for use in medical environments or for life-support
applications.
Environment
The Yocto-Display is not certified for use in hazardous locations, explosive environments, or life-
threatening applications. Environmental ratings are provided below.
1.2. Environmental conditions
Yoctopuce devices have been designed for indoor use in a standard office or laboratory environment
(IEC 60664 pollution degree 2): air pollution is expected to be limited and mainly non-conductive.
Relative humidity is expected to be between 10% and 90% RH, non condensing. Use in
environments with significant solid pollution or conductive pollution requires a protection from such
pollution using an IP67 or IP68 enclosure. The products are designed for use up to altitude 2000m.
All Yoctopuce devices are warranted to perform according to their documentation and technical
specifications under normal temperature conditions according to IEC61010-1, i.e. 5°C to 40°C. In
addition, most devices can also be used on an extended temperature range, where some limitations
may apply from case to case.
The extended operating temperature range for the Yocto-Display is -25...70°C. This temperature
range has been determined based on components manufacturer recommendations, and on
controlled environment tests performed during a limited duration (1h). If you plan to use the Yocto-
Display in harsh environments for a long period of time, we strongly advise you to run extensive tests
before going to production.
1. Introduction
2 www.yoctopuce.com

2. Presentation
1: Micro-B USB socket 4: Test anButtons 1 to 6
2: Yocto-button 5: anButtons inputs 1 to 6
3: Yocto-led 6: Common ground
2.1. Common elements
All Yocto-modules share a number of common functionalities.
USB connector
Yoctopuce modules all come with a USB 2.0 micro-B socket. 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.
If you plan to use a power source other then a standard USB host port to power the device through
the USB connector, that power source must respect the assigned values of USB 2.0 specifications:
•Voltage min.: 4.75 V DC
•Voltage max.: 5.25 V DC
•Over-current protection: 5.0 A max.
www.yoctopuce.com 3

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.
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-Display
modules, this number starts with YD128X32. 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 screen
The screen is an OLED screen manufactured by WiseChip under the UG-2832ALBCG01 reference.
Being made of glass, it is rather fragile. Do not let your Yocto-Display drop. When you install your
Yocto-Display, make sure that the screen is not subjected to any mechanical constraint. Moreover,
the ribbon coming out of the screen is particularly fragile at its junction with the screen. Make sure it
is not subject to any mechanical constraint. When you manipulate the Yocto-Display, do not press on
the ribbon.
1 short-short-short long-long-long short-short-short
2 [email protected]
2. Presentation
4 www.yoctopuce.com