The Yocto-MaxiBuzzer module is a 57x58mm device equipped with a powerfull buzzer, one RGB LEDs, with the capability to drive many more, and two analog inputs able detect the state of switches, push button or potentiometer. This module is designed to provide a simple mean to create both ascoustic and visual alarms from a computer.
The Yocto-MaxiBuzzer module
The Yocto-MaxiBuzzer 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-MaxiBuzzer 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-MaxiBuzzer 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: | support@yoctopuce.com |
Web site: | www.yoctopuce.com |
Postal address: | Chemin des Journaliers, 1 |
ZIP code, city: | 1236 Cartigny |
Country: | Switzerland |
The Yocto-MaxiBuzzer 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.
The Yocto-MaxiBuzzer 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.
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.
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. This label is resistant to humidity, and can hand rubbing with a piece of cloth soaked with water.
Identification label is integrated in the package label.
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-MaxiBuzzer for another kind of application, you should check the safety regulations according to the standard applicable to your application.
In particular, the Yocto-MaxiBuzzer is not certified for use in medical environments or for life-support applications.
The Yocto-MaxiBuzzer is not certified for use in hazardous locations, explosive environments, or life-threatening applications. Environmental ratings are provided below.
The Yocto-MaxiBuzzer has been designed to work with safety extra-low voltages only. Do not exceed voltages indicated in this manual, and never connect to the Yocto-MaxiBuzzer terminal blocks any wire that could be connected to the mains.
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-MaxiBuzzer is -25...80°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-MaxiBuzzer in harsh environments for a long period of time, we strongly advise you to run extensive tests before going to production.
1: | Yocto-LED | 6: | Test input 1 |
2: | Yocto-button | 7: | Input 2 |
3: | USB connector | 8: | Test input 2 |
4: | Buzzer | 9: | RGB LED |
5: | Input 1 | 10: | RGB LEDs output |
All Yocto-modules share a number of common functionalities.
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:
A higher voltage is likely to destroy the device. THe behaviour with a lower voltage is not specified, but it can result firmware corruption.
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.
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.
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.
Each Yocto-module has a unique serial number assigned to it at the factory. For Yocto-MaxiBuzzer modules, this number starts with YMAXBUZ1. The module can be software driven using this serial number. The serial number cannot be modified.
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.
The buzzer embedded in the Yocto-MaxiBuzzer module can generate a sound between 25 and 5000 Hz with about 100dB(A) maximum power output. The volume can be controlled at will, but the selected frequency also has a significant impact on the output power of the speaker. The Yoctopuce API allows you to pre-program simple sound patterns as sequences, which can be played without external intervention.
This LED has the particularity of being able to emit three colors simultaneously: red, green, and blue. They are in fact three distinct LEDs housed in the same case. By modulating with high precision the power of each of these three LEDs, the device can create almost any color, including white.
The RGB LED used in the Yocto-MaxiBuzzer is a so-called "smart" LEDs which can be chained. Such LEDs are designed to receive as input a digital command signal that they can interpret and then re-direct on their output towards the following LEDs in the string. This technology makes it possible to chain a large number of these LEDs with only three wires: ground, 5V, and signal. The Yocto-MaxiBuzzer can drive up to 150 LEDs simultaneously, as long as enough current is provided on the USB port. The smart LED driving logic is compatible with RGB LEDs type WS2812B, WS2812C, SK6812, and RGBW LEDs type SK6812RGBW, which makes it possible to use this module with numerous devices based on these LEDs3. For more details, see the diagrams in chapter Assembly and connections.
The Yocto-MaxiBuzzer module has two inputs with a common earth able to detect the state of any resistive device such as push button, switch, potentiometer, photo-diode, reed contacts etc... You can use any potentiometer value between 1KΩ and 200 KΩ.
Writing example for a potentiometer , push button and extra RGB leds
Your Yocto-MaxiBuzzer module is able to measure whether push buttons and switches connected to it are open or closed, in the same way it is able to measure the relative location of potentiometers connected to it. Actually, the module merely measures the resistance of each connected circuit.
The measurement circuit is a safety extra low voltage (SELV) circuit. It should not be connected to any external voltage source, but only be connected to passive components. In no event shall it be connected to mains circuits.
This module allows you to use a large range of potentiometer values. However, for the module to provide you with coherent measures for the model you use, you need to calibrate the corresponding channels. This can be done very easily thanks to the configuration interface. Calibration is not necessary if you use only simple switches or push buttons.
The accessories below are not necessary to use the Yocto-MaxiBuzzer 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.
In order to mount the Yocto-MaxiBuzzer module, you can put small screws in the 3mm assembly holes, with a screw head no larger than 8mm. 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.
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.
You can add network connectivity to your Yocto-MaxiBuzzer, 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.
In case you wish to connect your Yocto-MaxiBuzzer 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-MaxiBuzzer 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-MaxiBuzzer.
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.
Your Yocto-MaxiBuzzer has been designed to be installed as is in your project. Nevertheless, Yoctopuce sells enclosures specifically designed for Yoctopuce devices. More details are available on the Yoctopuce web site 4. The suggested enclosure model for your Yocto-MaxiBuzzer is the YoctoBox-MaxiBuz.
You can install your Yocto-MaxiBuzzer in an optional enclosure
If you want add LEDs to the Yocto-MaxiBuzzer module, you can rewire the parts by using servo-motor wire and headers (either bent or not), with a 2.54mm pitch.
You can use servo wire to add LEDs the module
The Yocto-MaxiBuzzer can drive up to 150 digital RGB LEDs simulteanously, as long as they are of type WS2812B, WS2812C, SK6812 (RGB) or WS2812B, WS2812C, SK6812 (RGBW). You can find on the market PCBs with these LEDs as strips, matrixes, sticks, or even rings. Yoctopuce does not sell this type of accessories, but you can find them for examples at Adafruit5 under the NEOPIXEL brand.
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.
In order to use your Yocto-MaxiBuzzer module, you should have the following items at hand.
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, macOS X, Linux, and Android. Yoctopuce modules do not require installing any specific system driver, as they leverage the standard HID driver6 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. The programming library is also available for the Universal Windows Platform (UWP), which is supported by all flavors of Windows 10, including Windows 10 IoT. Yoctopuce is frequently testing its modules on Windows 7 and Windows 10.
MacOS versions currently supported are: Mac OS X 10.9 (Maverick), 10.10 (Yosemite), 10.11 (El Capitan), macOS 10.12 (Sierra), macOS 10.13 (High Sierra) and macOS 10.14 (Mojave). Yoctopuce is frequently testing its modules on macOS 10.14.
Linux kernels currently supported are the 2.6 branch, the 3.x branch and the 4.x 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 4.15 (Ubuntu 18.04 LTS).
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 7.x on a Samsung Galaxy A6 with the Java for Android library.
USB 2.0 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.0 connectors: A, B, Mini B, Micro A, Micro B7
To connect your Yocto-MaxiBuzzer module to a computer, you need a USB 2.0 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 2.0 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-MaxiBuzzer module with a USB 2.0 cable of type A - micro B
If you insert a USB hub between the computer and the Yocto-MaxiBuzzer 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.
At this point, your Yocto-MaxiBuzzer 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 software8. 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 browser9. 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
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.
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-MaxiBuzzer.
Properties of the Yocto-MaxiBuzzer module
This window allows you, among other things, to test the buzzer by changing the frequency and the volume, to test the analog inputs, to change the RGB LEDs color.
When, in the module list, you click on the configure button corresponding to your module, the configuration window is displayed.
Yocto-MaxiBuzzer module configuration.
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 10 in command line 11.
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.
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.
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.
Five functions are available on the device: a Buzzer corresponding to the buzzer, a ColorLed corresponding to the RGB LED built on the device, one ColorLedCluster corresponding to the external RGB LEDs, and two AnButton for the analog inputs.
The ColorLedCluster function allows you to drive an arbitrary number of RGB LEDs, up to 150. The controller will work whether the LEDs are connected or not. However, the more LEDs to be driven, the higher the demand on the module processor. When this parameter is set to the maximum, small saccades could appear during automatic transitions. You might therefore not wish to configure the module to drive LEDs that do not exist.
This module can store a power-on color for each LED. Simply click on the color square corresponding to the LED that you want to configure to obtain a color palette. You can also use the current color of the LEDs as power-on color.
A typical application of this function is to configure the LEDs power-on color from a computer, and then to power them from a simple USB charger. This is an easy way to build a custom lighting solution.
This chapter provides important information regarding the use of the Yocto-MaxiBuzzer module in real-world situations. Make sure to read it carefully before going too far into your project if you want to avoid pitfalls.
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-MaxiBuzzer module contains 3mm assembly holes. You can use these holes for screws. The screw head diameter must not be larger than 8mm 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.
The Yocto-MaxiBuzzer features a LED output allowing to add extra LEDs to the system. Such LED are availbale from many suppliers and many form factor are available: strip, sticks, matrix etc... You can also reuse LEDs from Yocto-Color-V212.
The Yocto-MaxiBuzzer features an output to drive extra LEDs
There are several solutions available for connecting extra LEDs. You can connect the sub-modules by soldering simple electric cables: it is the most accessible solution, but it is far from being the most convenient. The three parts of the module all have three holes with a standard 2.54mm pitch. You can solder there a terminal13. You can also use bent headers at the 2.54mm pitch and model making servo-motor wires.
Submodule wiring example with servo wires
You need three wires to connect submodules: signal, 5V, and ground. On the Yocto-MaxiBuzzer, ground is shown with a square pad.
Be careful, you must always connect the modules serially, that is chained. Each submodule has an input and an output, the output of each submodule must be connected to the input of the following submodule. The length of the wire between two neighboring LEDs must be under 1 meter.
Pay attention to polarity and to the LED direction, each has an input and an output
You can also connect any LED device based on models WS2812B, WS2812C, SK6812 (RGB) or WS2812B, WS2812C, SK6812 (RGBW) up to a maximum of 150 distinct LEDs.
The Yocto-MaxiBuzzer can drive many more many LEDs
There is no direct software manner to know how many LEDs are connected to the controller sub-module. But you can make an educated guess by testing the variations in power consumption of the module: if you order to turn a LED on and the power consumption increases, then it means that the corresponding LED is present.
Each of the Yocto-MaxiBuzzer LEDs can consume up to 45mA when it emits white light at full power. However, a USB module is not supposed to consume more than 500mA. The Yocto-MaxiBuzzer is itself able to go above this 500mA limit, but it is going to heat up. Therefore, if you intend to use many LEDs and think that you will go largely above the 500mA, you should use an external power supply, wired as per the illustration below.
Wiring with an external power supply
Each of these "smart" LEDs contains a small processor and comes with a small SMD condenser, usually soldered close to the LED, used to insure a reasonably stable power supply. If a large number of LEDs are connected at once to a Yocto-MaxiBuzzer already powered, the brief voltage drop due to the great power demand caused by the numerous condensers connected serially can make the Yocto-MaxiBuzzer restart. This behavior is normal.
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 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 you controlling and planning overall power consumption for your project, all Yoctopuce modules include a built-in current sensor that indicates (with 5mA precision) the consumption of the module on the USB bus.
Note also that the USB cable itself may also cause power supply issues, in particular when the wires are too thin or when the cable is too long 14. Good cables are usually made using AWG 26 or AWG 28 wires for data lines and AWG 24 wires for power.
Connection methods to integrate the Yocto-MaxiBuzzer obviously have an impact on the system overall electromagnetic emissions, and therefore also impact the conformity with international standards.
When we perform reference measurements to validate the conformity of our products with IEC CISPR 11, we do not use any enclosure but connect the devices using a shielded USB cable, compliant with USB 2.0 specifications: the cable shield is connected to both connector shells, and the total resistance from shell to shell is under 0.6Ω. The USB cable length is 3m, in order to expose one meter horizontally, one meter vertically and keep the last meter close to the host computer within a ferrite bead.
If you use a non-shielded USB cable, or an improperly shielded cable, your system will work perfectly well but you may not remain in conformity with the emission standard. If you are building a system made of multiple devices connected using 1.27mm pitch connectors, or with a sensor moved away from the device CPU, you can generally recover the conformity by using a metallic enclosure acting as an external shield.
Still on the topic of electromagnetic compatibility, the maximum supported length of the USB cable is 3m. In addition to the voltage drop issue mentionned above, using longer wires would require to run extra tests to assert compatibility with the electromagnetic immunity standards.
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 Yocto-MaxiBuzzer 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.
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.
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.
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.
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-MaxiBuzzer 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.
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.
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.
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.
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.
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.
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.
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.
The Yocto-MaxiBuzzer module provides two instance of the Led function, corresponding to both leds present on the module. There are two instances of the anButton function for the two analog inputs. There is also one instance of the buzzer function allowing you to drive the device buzzer.
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 |
attribute | type | modifiable ? |
---|---|---|
logicalName | String | modifiable |
advertisedValue | String | modifiable |
calibratedValue | Integer | read-only |
rawValue | Integer | read-only |
analogCalibration | On/Off | modifiable |
calibrationMax | Integer | modifiable |
calibrationMin | Integer | modifiable |
sensitivity | Integer | modifiable |
isPressed | Boolean | read-only |
lastTimePressed | Time | read-only |
lastTimeReleased | Time | read-only |
pulseCounter | Integer | modifiable |
pulseTimer | Time | read-only |
inputType | Enumerated | modifiable |
attribute | type | modifiable ? |
---|---|---|
logicalName | String | modifiable |
advertisedValue | String | modifiable |
frequency | Fixed-point number | modifiable |
volume | 0..100% | modifiable |
playSeqSize | Integer | read-only |
playSeqMaxSize | Integer | read-only |
playSeqSignature | Integer | read-only |
command | String | modifiable |
attribute | type | modifiable ? |
---|---|---|
logicalName | String | modifiable |
advertisedValue | String | modifiable |
rgbColor | 24bit integer | modifiable |
hslColor | 24bit integer | modifiable |
rgbMove | Aggregate | modifiable |
hslMove | Aggregate | modifiable |
rgbColorAtPowerOn | 24bit integer | modifiable |
blinkSeqSize | Integer | read-only |
blinkSeqMaxSize | Integer | read-only |
blinkSeqSignature | Integer | read-only |
command | String | modifiable |
attribute | type | modifiable ? |
---|---|---|
logicalName | String | modifiable |
advertisedValue | String | modifiable |
activeLedCount | Integer | modifiable |
ledType | Enumerated | modifiable |
maxLedCount | Integer | read-only |
blinkSeqMaxCount | Integer | read-only |
blinkSeqMaxSize | Integer | read-only |
command | String | modifiable |
attribute | type | modifiable ? |
---|---|---|
logicalName | String | modifiable |
advertisedValue | String | modifiable |
filesCount | Integer | read-only |
freeSpace | Integer | read-only |
Global parameters control interface for all Yoctopuce devices
The YModule class can be used with all Yoctopuce USB devices. It can be used to control the module global parameters, and to enumerate the functions provided by each module.
Character string containing the commercial name of the module, as set by the factory.
Character string containing the serial number, unique and programmed at the factory. For a Yocto-MaxiBuzzer module, this serial number always starts with YMAXBUZ1. You can use the serial number to access a given module by software.
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 -.
USB device identifier of the module, preprogrammed to 152 at the factory.
Release number of the module hardware, preprogrammed at the factory. The original hardware release returns value 1, revision B returns value 2, etc.
Release version of the embedded firmware, changes each time the embedded software is updated.
State of persistent module settings: loaded from flash memory, modified by the user or saved to flash memory.
Lighting strength of the informative leds (e.g. the Yocto-Led) contained in the module. It is an integer value which varies between 0 (LEDs turned off) and 100 (maximum led intensity). The default value is 50. To change the strength of the module LEDs, or to turn them off completely, you only need to change this value.
Activity of the localization beacon of the module.
Time elapsed since the last time the module was powered on.
Current consumed by the module on the USB bus, in milli-amps.
Countdown to use for triggering a reboot of the module.
32bit integer variable available for user storage.
buzzer control interface, available for instance in the Yocto-Buzzer or the Yocto-MaxiBuzzer
The YBuzzer class allows you to drive a buzzer. You can choose the frequency and the volume at which the buzzer must sound. You can also pre-program a play sequence.
Character string containing the logical name of the buzzer, 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 the buzzer directly. If two buzzers with the same logical name are used 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 -.
Current frequency, automatically advertised up to the parent hub.
Frequency of the signal sent to the buzzer/speaker
Volume of the signal sent to the buzzer/speaker
Play sequence current size
Play sequence maximum size
Play sequence signature
Magic attribute used to send advanced commands to the device. If a command is not interpreted as expected, check the device logs.
analog input control interface, available for instance in the Yocto-Buzzer, the Yocto-Knob, the Yocto-MaxiBuzzer or the Yocto-MaxiDisplay
The YAnButton class provide access to basic resistive inputs. Such inputs can be used to measure the state of a simple button as well as to read an analog potentiometer (variable resistance). This can be use for instance with a continuous rotating knob, a throttle grip or a joystick. The module is capable to calibrate itself on min and max values, in order to compute a calibrated value that varies proportionally with the potentiometer position, regardless of its total resistance.
Character string containing the logical name of the analog input, 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 the analog input directly. If two analog inputs with the same logical name are used 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 -.
Short character string summarizing the current state of the analog input, that is be automatically advertised up to the parent hub. For an analog input, the advertised value is the calibrated measured value (a number between 0 and 1000).
Calibrated value of the anlog input, as an integer from 0 to 1000, included. If no calibration has been run, the calibrated value is simply the measured value, scaled down to the range 0...1000, without linearity correction.
Measured value of the analog input, as is, formatted as an integer from 0 to 4095. The measured value is zero when the input resistance is zero (closed contact), and reaches 4095 as the input resistance moves toward infinity (open contact). Be aware that this value does not vary linearly with regard to the input resistance (and to the known position). If you need a linear value, perform a calibration and use the computed value calibratedValue.
Use this attribute to start and stop the calibration process for the analog input. When the calibration is enabled, the module records the minimal and maximal measured values into calibrationMin and calibrationMax. Once the calibration is over (stopped), the module can automatically compute a running calibrated value for the every measure, varying linearly with the measured resistance value.
Maximal observed raw measure during calibration. You can also change this value by software if you want to force a theoretical calibration.
Minimal observed raw measure during calibration. You can also change this value by software if you want to force a theoretical calibration.
Sensitivity of the analog input to trigger user callbacks. The sensitivity corresponds to the difference of value required to propagate a new advertised value and trigger the corresponding user callbacks. If the value is too small, it could cause spurious callbacks if the measured input is not stable enough.
Logical state of the input, considered as a binary input (on/off button). The logical state is pressed when the contact is closed, and non-pressed when the contact is open. The module implements a slight averaging and a Schmitt trigger to get a more reliable binary reading.
Absolute time of the last "button pressed" event on the input (the input contact transitioned from open to closed). The time reference is the same as the upTime attribute, i.e. the elapsed time since the module was turned on.
Absolute time of the last "button released" event on the input (the input contact transitioned from closed to open). The time reference is the same as the upTime attribute, i.e. the elapsed time since the module was turned on. If you subtract from this value the lastTimePressed value, you can get the duration of the last button pressure.
Pulse counter (32 bits), incremented each time the button state changes (PRESSED / RELEASED), Each pulse therefore increment the counter by 2. This counter is set to zero when resetCounter() is called and each time the device restarts
Elapsed time since last pulse counter reset (milliseconds).
Type of knob connected to the input (analog or multiplexed binary switches)
RGB LED control interface, available for instance in the Yocto-Color-V2, the Yocto-MaxiBuzzer or the Yocto-PowerColor
The ColorLed class allows you to drive a color LED. The color can be specified using RGB coordinates as well as HSL coordinates. The module performs all conversions form RGB to HSL automatically. It is then self-evident to turn on a LED with a given hue and to progressively vary its saturation or lightness. If needed, you can find more information on the difference between RGB and HSL in the section following this one.
Character string containing the logical name of the RGB LED, 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 the RGB LED directly. If two RGB LEDs with the same logical name are used 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 -.
Short character string summarizing the current state of the RGB LED, that will be automatically advertised up to the parent hub. For an RGB LED, the advertised value is the RGB color of the LED (6 hexadecimal digits).
Current color of the LED, in the shape of an integer encoded in RGB. To extract red, green, and blue components, your must: for red do a 16 bit shift to the right, for green do a 8 bit shift to the right and keep only the 8 bits on the right, for blue keep only the 8 bits on the right.
Current color of the LED (same as rgbColor), but encoded using the HSL color system.
Allows you to modify the current color of the LED to another one, in a seamless and autonomous manner. The value is an aggregate including the target RGB color as integer, and a duration in milliseconds.
Identical to rgbMove, but uses the HSL color system. In HSL, hue is a circular value (0..360°). There are always two paths to perform the transition: by increasing or by decreasing the hue. The module selects the shortest transition. If the difference is exactly 180°, the module selects the transition which increases the hue.
In HSL, the module selects the shortest hue transition. In case of a 180° difference,
the transition is performed clock-wise.
Color of the LED to be selected when the module is powered on.
Blinking sequence current size
Blinking sequence maximum size
Blinking sequence signature
Magic attribute used to send advanced commands to the device. If a command is not interpreted as expected, check the device logs.
RGB LED cluster control interface, available for instance in the Yocto-Color-V2 or the Yocto-MaxiBuzzer
The YColorLedCluster class allows you to drive a color LED cluster. Unlike the ColorLed class, the YColorLedCluster class allows to handle several LEDs at once. Color changes can be done using RGB coordinates as well as HSL coordinates. The module performs all conversions form RGB to HSL automatically. It is then self-evident to turn on a LED with a given hue and to progressively vary its saturation or lightness. If needed, you can find more information on the difference between RGB and HSL in the section following this one.
Character string containing the logical name of the RGB LED cluster, 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 the RGB LED cluster directly. If two RGB LED clusters with the same logical name are used 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 -.
Short character string summarizing the current state of the RGB LED cluster, that will be automatically advertised up to the parent hub. For a RGB LED cluster, the advertised value is the checksum of the LED buffer (6 hexadecimal digits).
Number of LEDs currently handled by the device
Type of RGB LED currently handled by the device
Maximum count of LEDs the device can handle
Maximum count of recorded sequences
Sequence maximum size
Magic attribute used to send advanced commands to the device. If a command is not interpreted as expected, check the device logs.
There are several manners to define a color. The most common one consists in using its red, green, and blue (RGB) components. You can indeed define each color as a mix of these three primary colors. Unfortunately, this system is relatively hard to manipulate precisely as soon as you must define an unsaturated color. For example, to obtain pink requires some trials and errors before getting the desired result.
The RGB color space, it is often represented in the shape of a cube.
In computer science, the definition of an RGB color is given by a triplet 0..255 in hexadecimal number15. In this manner pure red is defined by 0xFF0000, pure green by 0x00FF00, pure blue by 0x0000FF, black by 0x000000, and white by 0xFFFFFF. This notation is used, for example, in HTML to define colors. The # prefix is then used instead of 0x.
There is another manner, somewhat simpler, to define a color. You decompose a color into hue, saturation, and lightness (HSL). Hue has values from 0° to 360°. It starts from red (0°), passing through yellow (60°), green (120°), cyan (180°), blue (240°), magenta (300°), to finally come back to red (360°). Saturation, with values from 0% to 100%, defines the intensity of a color: the closer to 0%, the more washed out a color appears; the closer to 100%, the brighter a color appears. Lightness with values from 0% to 100%, defines the clearness of a color. The color gets darker when the value gets closer to 0% and clearer when getting closer to 100%. It is much easier to predict how a color changes when one of the coordinates in the HSL color space is manipulated, than in the RGB color space.
The HSL color space. It is often represented as a double cone shape, with a black
base (L=0%) and a white top tip (L100%). Hue is mapped on the circumference,
Saturation on the radius.
In computer science, one tends to normalize the HSL coordinates over 0..255 and a hexadecimal triplet is used. Thus, 00FF80 is pure red, F0FF80 is pure blue. Note that is this system, several triplets can represent the same color: all triplets ending in 00 are black, all triplets ending in FF are white. A triplet with a saturation of 0 represents grey, whatever the hue value.
The Yocto-MaxiBuzzer can play animations autonomously, that is without a computer. These animations are based on a sequence concept. A sequence is a series of pseudo-instructions managed by the colorLedCluster class which can manage up to eight such sequences in parallel. Each led can only be assigned to one sequence at any given time.
A sequence is defined essentially as a series of color changes performed in a loop. Thus, the code below re-initializes the sequence #0 and adds two transitions: one towards red, and one towards blue. Each one lasts a second.
Thus, all the leds assigned to this sequence are going to seesaw between red and blue with a total period of two seconds. The following lines assign the first two leds to sequence #0 and starts the sequence.
The illustration below shows how the two leds evolve over time
Running an automatic red-blue sequence with a 2 second period
You can introduce an offset when linking leds to a sequence. The leds then still run the same sequence, but with an offset. The code below assigns led 0 to sequence #0 with a 0ms offset, then assigns led #1, still to sequence #0, but with a 1000ms offset.
Instead of changing color at the same time, the leds change color alternatively, as the offset was defined as half a period.
Running the preceding sequence wit a 1 second offset between the two leds
Offsets when running a sequence allow you to make very spectacular chase effects. Let us imagine that we have 5 leds connected serially to the Yocto-MaxiBuzzer, the following code creates a sequence that sets a led to blue for 200ms and then switches it off for 800ms.
Note that to instantaneously go from one color to another, you can simply use move with a zero duration. Running the sequence creates a blue light going from one led to the other every 200ms.
You can create a chase effect in a few lines
You can modify a sequence running speed. The default speed is 1000, but you can decrease it or even inverse it. Below, the code that switches a led from red to yellow and inversely with a 400ms period.
Red yellow alternation with a 400ms frequency (normal speed: 1000)
If you decrease the speed by a factor of 2 with set_blinkSeqSpeed, the period increases by a factor of 2, transitions remain progressive because they are computed in real time.
Same sequence, half speed (500)
Note, sequences are computed in real time. However, the Yocto-MaxiBuzzer leds are refreshed at a 100Hz rate. Therefore, a change lasting less than 10ms at normal speed is taken into account but risks not being displayed, as it does not last long enough.
You can store sequences in the Yocto-MaxiBuzzer non volatile memory, in the same way you can store the led assignments to distinct sequences. Moreover, you can configure a sequence so that it automatically starts at module power on. The following code configures a sequence, then saves everything so that it automatically starts the next time the module restarts next.
This technique allows you to build simple light effects which do not require a computer to work. If there are preprogrammed sequences in the module, you only need to power it with a simple USB charger so that the sequences start as soon as the module is powered.
There are several methods to control you Yoctopuce module by software.
In this case, the software driving your project is compiled directly with a library which provides control of the modules. Objectively, it is the simplest and most elegant solution for the end user. The end user then only needs to plug the USB cable and run your software for everything to work. Unfortunately, this method is not always available or even possible.
The application uses the native library to control the locally connected module
Here, the main part of the code controlling the modules is located in a DLL. The software is compiled with a small library which provides control of the DLL. It is the fastest method to code module support in a given language. Indeed, the "useful" part of the control code is located in the DLL which is the same for all languages: the effort to support a new language is limited to coding the small library which controls the DLL. From the end user stand point, there are few differences: one must simply make sure that the DLL is installed on the end user's computer at the same time as the main software.
The application uses the DLL to natively control the locally connected module
Some languages do simply not allow you to easily gain access to the hardware layers of the machine. It is the case for Javascript, for instance. To deal with this case, Yoctopuce provides a solution in the form of a small piece of software called VirtualHub16. It can access the modules, and your application only needs to use a library which offers all necessary functions to control the modules via this VirtualHub. The end users will have to start the VirtualHub before running the project control software itself, unless they decide to install the hub as a service/deamon, in which case the VirtualHub starts automatically when the machine starts up.
The application connects itself to the VirtualHub to gain access to the module
The service control method comes with a non-negligible advantage: the application does not need to run on the machine on which the modules are connected. The application can very well be located on another machine which connects itself to the service to drive the modules. Moreover, the native libraries and DLL mentioned above are also able to connect themselves remotely to one or several machines running VirtualHub.
When a VirtualHub is used, the control application does not need
to reside on the same machine as the module.
Whatever the selected programming language and the control paradigm used, programming itself stays strictly identical. From one language to another, functions bear exactly the same name, and have the same parameters. The only differences are linked to the constraints of the languages themselves.
Language | Native | Native with DLL | VirtualHub |
---|---|---|---|
Command line | ✔ | - | ✔ |
Python | - | ✔ | ✔ |
C++ | ✔ | ✔ | ✔ |
C# .Net | - | ✔ | ✔ |
C# UWP | ✔ | - | ✔ |
LabVIEW | - | ✔ | ✔ |
Java | - | ✔ | ✔ |
Java for Android | ✔ | - | ✔ |
TypeScript | - | - | ✔ |
JavaScript / ECMAScript | - | - | ✔ |
PHP | - | - | ✔ |
VisualBasic .Net | - | ✔ | ✔ |
Delphi | - | ✔ | ✔ |
Objective-C | ✔ | - | ✔ |
Natives et DLL libraries have a technical limitation. On the same computer, you cannot concurrently run several applications accessing Yoctopuce devices directly. If you want to run several projects on the same computer, make sure your control applications use Yoctopuce devices through a VirtualHub software. The modification is trivial: it is just a matter of parameter change in the yRegisterHub() call.
At this point of the user's guide, you should know the main theoretical points of your Yocto-MaxiBuzzer. It is now time to practice. You must download the Yoctopuce library for your favorite programming language from the Yoctopuce web site17. Then skip directly to the chapter corresponding to the chosen programming language.
All the examples described in this guide are available in the programming libraries. For some languages, the libraries also include some complete graphical applications, with their source code.
When you have mastered the basic programming of your module, you can turn to the chapter on advanced programming that describes some techniques that will help you make the most of your Yocto-MaxiBuzzer.
When you want to perform a punctual operation on your Yocto-MaxiBuzzer, such as reading a value, assigning a logical name, and so on, you can obviously use the Virtual Hub, but there is a simpler, faster, and more efficient method: the command line API.
The command line API is a set of executables, one by type of functionality offered by the range of Yoctopuce products. These executables are provided pre-compiled for all the Yoctopuce officially supported platforms/OS. Naturally, the executable sources are also provided18.
Download the command line API19. You do not need to run any setup, simply copy the executables corresponding to your platform/OS in a directory of your choice. You may add this directory to your PATH variable to be able to access these executables from anywhere. You are all set, you only need to connect your Yocto-MaxiBuzzer, open a shell, and start working by typing for example:
To use the command API on Linux, you need either have root privileges or to define an udev rule for your system. See the Troubleshooting chapter for more details.
All the command line API executables work on the same principle. They must be called the following way
[options] manage the global workings of the commands, they allow you, for instance, to pilot a module remotely through the network, or to force the module to save its configuration after executing the command.
[target] is the name of the module or of the function to which the command applies. Some very generic commands do not need a target. You can also use the aliases "any" and "all", or a list of names separated by comas without space.
command is the command you want to run. Almost all the functions available in the classic programming APIs are available as commands. You need to respect neither the case nor the underlined characters in the command name.
[parameters] logically are the parameters needed by the command.
At any time, the command line API executables can provide a rather detailed help. Use for instance:
to know the list of available commands for a given command line API executable, or even:
to obtain a detailed description of the parameters of a command.
To control the Buzzer function of your Yocto-MaxiBuzzer, you need the YBuzzer executable file.
For instance, you can launch:
This example uses the "any" target to indicate that we want to work on the first Buzzer function found among all those available on the connected Yoctopuce modules when running. This prevents you from having to know the exact names of your function and of your module.
But you can use logical names as well, as long as you have configured them beforehand. Let us imagine a Yocto-MaxiBuzzer module with the YMAXBUZ1-123456 serial number which you have called "MyModule", and its buzzer function which you have renamed "MyFunction". The five following calls are strictly equivalent (as long as MyFunction is defined only once, to avoid any ambiguity).
To work on all the Buzzer functions at the same time, use the "all" target.
For more details on the possibilities of the YBuzzer executable, use:
Each module can be controlled in a similar way with the help of the YModule executable. For example, to obtain the list of all the connected modules, use:
You can also use the following command to obtain an even more detailed list of the connected modules:
Each xxx property of the module can be obtained thanks to a command of the get_xxxx() type, and the properties which are not read only can be modified with the set_xxx() command. For example:
When you want to change the settings of a module, simply use the corresponding set_xxx command. However, this change happens only in the module RAM: if the module restarts, the changes are lost. To store them permanently, you must tell the module to save its current configuration in its nonvolatile memory. To do so, use the saveToFlash command. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash method. For example:
Note that you can do the same thing in a single command with the -s option.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
The command line API has the same limitation than the other APIs: there can be only one application at a given time which can access the modules natively. By default, the command line API works in native mode.
You can easily work around this limitation by using a Virtual Hub: run the VirtualHub20 on the concerned machine, and use the executables of the command line API with the -r option. For example, if you use:
you obtain a list of the modules connected by USB, using a native access. If another command which accesses the modules natively is already running, this does not work. But if you run a Virtual Hub, and you give your command in the form:
it works because the command is not executed natively anymore, but through the Virtual Hub. Note that the Virtual Hub counts as a native application.
Python is an interpreted object oriented language developed by Guido van Rossum. Among its advantages is the fact that it is free, and the fact that it is available for most platforms, Windows as well as UNIX. It is an ideal language to write small scripts on a napkin. The Yoctopuce library is compatible with Python 2.6+ and 3+. It works under Windows, Mac OS X, and Linux, Intel as well as ARM. The library was tested with Python 2.6 and Python 3.2. Python interpreters are available on the Python web site21.
The Yoctopuce library classes22 for Python that you will use are provided as source files. Copy all the content of the Sources directory in the directory of your choice and add this directory to the PYTHONPATH environment variable. If you use an IDE to program in Python, refer to its documentation to configure it so that it automatically finds the API source files.
A section of the low-level library is written in C, but you should not need to interact directly with it: it is provided as a DLL under Windows, as a .so files under UNIX, and as a .dylib file under Mac OS X. Everything was done to ensure the simplest possible interaction from Python: the distinct versions of the dynamic library corresponding to the distinct operating systems and architectures are stored in the cdll directory. The API automatically loads the correct file during its initialization. You should not have to worry about it.
If you ever need to recompile the dynamic library, its complete source code is located in the Yoctopuce C++ library.
In order to keep them simple, all the examples provided in this documentation are console applications. Naturally, the libraries function in a strictly identical manner if you integrate them in an application with a graphical interface.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a Python code snipplet to use the Buzzer function.
Let's look at these lines in more details.
The yAPI.RegisterHub function initializes the Yoctopuce API and indicates where the modules should be looked for. When used with the parameter "usb", it will use the modules locally connected to the computer running the library. If the initialization does not succeed, this function returns a value different from YAPI.SUCCESS and errmsg contains the error message.
The YBuzzer.FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer.FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch Python and open the corresponding sample script provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library.
In this example, you will recognize the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type YModule.get_xxxx(), and properties which are not read-only can be modified with the help of the YModule.set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding YModule.set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the YModule.saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the YModule.revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the YModule.saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the YModule.yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not null. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
C++ is not the simplest language to master. However, if you take care to limit yourself to its essential functionalities, this language can very well be used for short programs quickly coded, and it has the advantage of being easily ported from one operating system to another. Under Windows, all the examples and the project models are tested with Microsoft Visual Studio 2010 Express, freely available on the Microsoft web site23. Under Mac OS X, all the examples and project models are tested with XCode 4, available on the App Store. Moreover, under Max OS X and under Linux, you can compile the examples using a command line with GCC using the provided GNUmakefile. In the same manner under Windows, a Makefile allows you to compile examples using a command line, fully knowing the compilation and linking arguments.
Yoctopuce C++ libraries24 are integrally provided as source files. A section of the low-level library is written in pure C, but you should not need to interact directly with it: everything was done to ensure the simplest possible interaction from C++. The library is naturally also available as binary files, so that you can link it directly if you prefer.
You will soon notice that the C++ API defines many functions which return objects. You do not need to deallocate these objects yourself, the API does it automatically at the end of the application.
In order to keep them simple, all the examples provided in this documentation are console applications. Naturally, the libraries function in a strictly identical manner if you integrate them in an application with a graphical interface. You will find in the last section of this chapter all the information needed to create a wholly new project linked with the Yoctopuce libraries.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a C++ code snipplet to use the Buzzer function.
Let's look at these lines in more details.
These two include files provide access to the functions allowing you to manage Yoctopuce modules. yocto_api.h must always be used, yocto_buzzer.h is necessary to manage modules containing a buzzer, such as Yocto-MaxiBuzzer.
The YAPI::RegisterHub function initializes the Yoctopuce API and indicates where the modules should be looked for. When used with the parameter "usb", it will use the modules locally connected to the computer running the library. If the initialization does not succeed, this function returns a value different from YAPI_SUCCESS and errmsg contains the error message.
The YBuzzer::FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer::FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer::FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by yFindBuzzer sets the buzzer frequency. The parameter is the desired frequency in Hz. A 0Hz frequency will stop the buzzer.
The set_volume() method of the objet returned by yFindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch your C++ environment and open the corresponding sample project provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library. If you prefer to work with your favorite text editor, open the file main.cpp, and type make to build the example when you are done.
In this example, you will recognize the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type get_xxxx(), and properties which are not read-only can be modified with the help of the set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not NULL. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
Depending on your needs and on your preferences, you can integrate the library into your projects in several distinct manners. This section explains how to implement the different options.
Integrating all the sources of the library into your projects has several advantages:
To integrate the source code, the easiest way is to simply include the Sources directory of your Yoctopuce library into your IncludePath, and to add all the files of this directory (including the sub-directory yapi) to your project.
For your project to build correctly, you need to link with your project the prerequisite system libraries, that is:
With the integration of the Yoctopuce library as a static library, you do not need to install a dynamic library specific to Yoctopuce, everything is in the executable.
To use the static library, you must first compile it using the shell script build.sh on UNIX, or build.bat on Windows. This script, located in the root directory of the library, detects the OS and recompiles all the corresponding libraries as well as the examples.
Then, to integrate the static Yoctopuce library to your project, you must include the Sources directory of the Yoctopuce library into your IncludePath, and add the sub-directory Binaries/... corresponding to your operating system into your libPath.
Finally, for you project to build correctly, you need to link with your project the Yoctopuce library and the prerequisite system libraries:
Note, under Linux, if you wish to compile in command line with GCC, it is generally advisable to link system libraries as dynamic libraries, rather than as static ones. To mix static and dynamic libraries on the same command line, you must pass the following arguments:
gcc (...) -Wl,-Bstatic -lyocto-static -Wl,-Bdynamic -lm -lpthread -lusb-1.0 -lstdc++
Integration of the Yoctopuce library as a dynamic library allows you to produce an executable smaller than with the two previous methods, and to possibly update this library, if a patch reveals itself necessary, without needing to recompile the source code of the application. On the other hand, it is an integration mode which systematically requires you to copy the dynamic library on the target machine where the application will run (yocto.dll for Windows, libyocto.so.1.0.1 for Mac OS X and Linux).
To use the dynamic library, you must first compile it using the shell script build.sh on UNIX, or build.bat on Windows. This script, located in the root directory of the library, detects the OS and recompiles all the corresponding libraries as well as the examples.
Then, To integrate the dynamic Yoctopuce library to your project, you must include the Sources directory of the Yoctopuce library into your IncludePath, and add the sub-directory Binaries/... corresponding to your operating system into your LibPath.
Finally, for you project to build correctly, you need to link with your project the dynamic Yoctopuce library and the prerequisite system libraries:
With GCC, the command line to compile is simply:
gcc (...) -lyocto -lm -lpthread -lusb-1.0 -lstdc++
C# (pronounced C-Sharp) is an object-oriented programming language promoted by Microsoft, it is somewhat similar to Java. Like Visual-Basic and Delphi, it allows you to create Windows applications quite easily. All the examples and the project models are tested with Microsoft C# 2010 Express, freely available on the Microsoft web site25.
Our programming library is also compatible with Mono, the open source version of C# that also works on Linux and MacOS. You will find on our web site various articles that describe how to configure Mono to use our library.
Download the Visual C# Yoctopuce library from the Yoctopuce web site26. There is no setup program, simply copy the content of the zip file into the directory of your choice. You mostly need the content of the Sources directory. The other directories contain the documentation and a few sample programs. All sample projects are Visual C# 2010, projects, if you are using a previous version, you may have to recreate the projects structure from scratch.
The Visual C#.NET Yoctopuce library is composed of a DLL and of source files in Visual C#. The DLL is not a .NET DLL, but a classic DLL, written in C, which manages the low level communications with the modules27. The source files in Visual C# manage the high level part of the API. Therefore, your need both this DLL and the .cs files of the sources directory to create a project managing Yoctopuce modules.
The following indications are provided for Visual Studio Express 2010, but the process is similar for other versions. Start by creating your project. Then, on the Solution Explorer panel, right click on your project, and select "Add" and then "Add an existing item".
A file selection window opens. Select the yocto_api.cs file and the files corresponding to the functions of the Yoctopuce modules that your project is going to manage. If in doubt, select all the files.
You then have the choice between simply adding these files to your project, or to add them as links (the Add button is in fact a scroll-down menu). In the first case, Visual Studio copies the selected files into your project. In the second case, Visual Studio simply keeps a link on the original files. We recommend you to use links, which makes updates of the library much easier.
Then add in the same manner the yapi.dll DLL, located in the Sources/dll directory28. Then, from the Solution Explorer window, right click on the DLL, select Properties and in the Properties panel, set the Copy to output folder to always. You are now ready to use your Yoctopuce modules from Visual Studio.
In order to keep them simple, all the examples provided in this documentation are console applications. Naturally, the libraries function in a strictly identical manner if you integrate them in an application with a graphical interface.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a C# code snipplet to use the Buzzer function.
Let's look at these lines in more details.
The YAPI.RegisterHub function initializes the Yoctopuce API and indicates where the modules should be looked for. When used with the parameter "usb", it will use the modules locally connected to the computer running the library. If the initialization does not succeed, this function returns a value different from YAPI.SUCCESS and errmsg contains the error message.
The YBuzzer.FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer.FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch Microsoft Visual C# and open the corresponding sample project provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library.
In this example, you will recognize the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type YModule.get_xxxx(), and properties which are not read-only can be modified with the help of the YModule.set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding YModule.set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the YModule.saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the YModule.revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the YModule.saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the YModule.yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not null. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
LabVIEW is edited by National Instruments since 1986. It is a graphic development environment: rather than writing lines of code, the users draw their programs, somewhat like a flow chart. LabVIEW was designed mostly to interface measuring tools, hence the Virtual Instruments name for LabVIEW programs. With visual programming, drawing complex algorithms becomes quickly fastidious. The LabVIEW Yoctopuce library was thus designed to make it as easy to use as possible. In other words, LabVIEW being an environment extremely different from other languages supported by Yoctopuce, there are major differences between the LabVIEW API and the other APIs.
The LabVIEW library is based on the Yoctopuce DotNetProxy library contained in the DotNetProxyLibrary.dll DLL. In fact, it is this DotNetProxy library which takes care or most of the work by relying on the C# library which, in turn, uses the low level library coded in yapi.dll (32bits) and amd64\yapi.dll( 64bits).
LabVIEW Yoctopuce API architecture
You must therefore imperatively distribute the DotNetProxyLibrary.dll, yapi.dll, and amd64\yapi.dll with your LabVIEW applications using the Yoctopuce API.
If need be, you can find the low level API sources in the C# library and the DotNetProxyLibrary.dll sources in the DotNetProxy library.
For the LabVIEW Yoctopuce library to work correctly with your Yoctopuce modules, these modules need to have firmware 37120, or higher.
At the time of writing, the LabVIEW Yoctopuce API has been tested under Windows only. It is therefore most likely that it simply does not work with the Linux and MacOS versions of LabVIEW.
The LabVIEW Yoctopuce library uses many techniques which are not yet available in the new generation of LabVIEW. The library is therefore absolutely not compatible with LabVIEW NXG.
In order to be compatible with as many versions of Windows as possible, including Windows XP, the DotNetProxyLibrary.dll library is compiled in .NET 3.5, which is available by default on all the Windows versions since XP.
Download the LabVIEW library from the Yoctopuce web site29. It is a ZIP file in which there is a distinct directory for each version of LabVIEW. Each of these directories contains two subdirectories: the first one contains programming examples for each Yoctopuce product; the second one, called VIs, contains all the VIs of the API and the required DLLs.
Depending on Windows configuration and the method used to copy the DotNetProxyLibrary.dll on your system, Windows may block it because it comes from an other computer. This may happen when the library zip file is uncompressed with Window's file explorer. If the DLL is blocked, LabVIEW will not be able to load it and an error 1386 will occur whenever any of the Yoctopuce VIs is executed.
There are two ways to fix this. The simplest is to unblock the file with the Windows file explorer: right click / properties on the DotNetProxyLibrary.dll file, and click on the unblock button. But this has to be done each time a new version of the DLL is copied on your system.
Unblock the DotNetProxyLibrary DLL.
Alternatively, one can modify the LabVIEW configuration by creating, in the same directory as the labview.exe executable, an XML file called labview.exe.config containing the following code:
Make sure to select the correct directory depending on the LabVIEW version you are using (32 bits vs. 64 bits). You can find more information about this file on the National Instruments web site.30
To install the LabVIEW Yoctopuce API, there are several methods.
The simplest way to use the Yoctopuce library is to copy the content of the VIs directory wherever you want and to use the VIs in LabVIEW with a simple drag-n-drop operation.
To use the examples provided with the API, it is simpler if you add the directory of Yoctopuce VIs into the list of where LabVIEW must look for VIs that it has not found. You can access this list through the Tools > Options > Paths > VI Search Path menu.
Configuring the "VI Search Path"
In each LabVIEW folder of the Library, you will find a VI named "Install.vi", just open the one matching your LabVIEW version.
The provider installer
This installer provide 3 installation options:
With this option, VI files are keep in the place where the library has been unzipped. So you will have to make sure these files are not deleted as long as you need them. Here is what the installer will do if that option is chosen:
In that case all required files are copied inside the LabVIEW's installation folder, so you will be able to delete the installation folder once the original installation is complete. Note that programming examples won't be copied. Here is the exact behaviour of the installer in that case:
this option is meant to remove the LabVIEW library from your LabVIEW installation, here is how it is done:
In any case, if the labview.ini file needs to be modified, a backup copy will be made beforehand.
The installer identifies Yoctopuce VIs library folders by checking the presence of the YRegisterHub.vi file in said folders.
Once the installation is complete, a Yoctopuce palette will appear in Functions/Addons menu.
The steps to manually install the VIs directly in the LabVIEW palette are somewhat more complex. You can find the detailed procedure on the National Instruments web site 31, but here is a summary:
Three windows pop up:
In the Function window, there is a Yoctopuce icon. Double-click it to create an empty "Yoctopuce" window.
The LabVIEW Yoctopuce library contains one VI per class of the Yoctopuce API, as well as a few special VIs. All the VIs have the traditional connectors Error IN and Error Out.
The YRegisterHub VI is used to initialize the API. You must imperatively call this VI once before you do anything in relation with Yoctopuce modules.
The YRegisterHub VI
The YRegisterHub VI takes a url parameter which can be:
In the case of an IP address, the YRegisterHub VI tries to contact this address and generates and error if it does not succeed, unless the async parameter is set to TRUE. If async is set to TRUE, no error is generated and Yoctopuce modules corresponding to that IP address become automatically available as soon as the said machine can be reached.
If everything went well, the successful output contains the value TRUE. In the opposite case, it contains the value FALSE and the error msg output contains a string of characters with a description of the error.
You can use several YRegisterHub VIs with distinct URLs if you so wish. However, on the same machine, there can be only one process accessing local Yoctopuce modules directly by USB (url set to "usb"). You can easily work around this limitation by running the VirtualHub software on the local machine and using the "127.0.0.1" url.
The YFreeAPI VI enables you to free resources allocated by the Yoctopuce API.
The YFreeAPI VI
You must call the YFreeAPI VI when your code is done with the Yoctopuce API. Otherwise, direct USB access (url set to "usb") could stay locked after the execution of your VI, and stay so for as long as LabVIEW is not completely closed.
The other VIs correspond to each function/class of the Yoctopuce API, they all have the same structure:
Structure of most VIs of the API.
You can find the list of functions available on your Yocto-MaxiBuzzer in chapter Programming, general concepts.
If the desired function (parameter name) is not available, this does not generate an error, but the is online output contains FALSE and all the other outputs contain the value "N/A" whenever possible. If the desired function becomes available later in the life of your program, is online switches to TRUE automatically.
If the name parameter contains an empty string, the VI targets the first available function of the same type. If no function is available, is online is set to FALSE.
The YModule VI enables you to interface with the "module" section of each Yoctopuce module. It enables you to drive the module led and to know the serial number of the module.
The YModule VI
The name input works slightly differently from other VIs. If it is called with a name parameter corresponding to a function name, the YModule VI finds the Module function of the module hosting the function. You can therefore easily find the serial number of the module of any function. This enables you to build the name of other functions which are located on the same module. The following example finds the first available YHumidity function and builds the name of the YTemperature function located on the same module. The examples provided with the Yoctopuce API make extensive use of this technique.
Using the YModule VI to retrieve functions hosted on the same module
All the VIs corresponding to Yoctopuce sensors have exactly the same geometry. Both outputs enable you to retrieve the value measured by the corresponding sensor as well the unit used.
The sensor VIs have all exactly the same geometry
The update freq input parameter is a character string enabling you to configure the way in which the output value is updated:
The update frequency of the VI is a parameter managed by the physical Yoctopuce module. If several VIs try to change the frequency of the same sensor, the valid configuration is that of the latest call. It is however possible to set different update frequencies to different sensors on the same Yoctopuce module.
Changing the update frequency of the same module
The update frequency of the VI is completely independent from the sampling frequency of the sensor, which you usually cannot modify. It is useless and counterproductive to define an update frequency higher than the sensor sampling frequency.
Here is one of the simplest example of VIs using the Yoctopuce API.
Minimal example of use of the LabVIEW Yoctopuce API
This example is based on the YSensor VI which is a generic VI enabling you to interface any sensor function of a Yoctopuce module. You can replace this VI by any other from the Yoctopuce API, they all have the same geometry and work in the same way. This example is limited to three actions:
This example automatically looks for an available sensor. If there is such a sensor, we can retrieve its name through the hardware name output and the isOnline output equals TRUE. If there is no available sensor, the VI does not generate an error but emulates a ghost sensor which is "offline". However, if later in the life of the application, a sensor becomes available because it has been connected, isOnline switches to TRUE and the hardware name contains the name of the sensor. We can therefore easily add a few indicators in the previous example to know how the executions goes.
Use of the hardware name and isOnline outputs
The VIs of the Yoctopuce API are actually an entry door into the library. Internally, this mechanism works independently of the Yoctopuce VIs. Indeed, most communications with electronic modules are managed automatically as background tasks. Therefore, you do not necessarily need to take any specific care to use Yoctopuce VIs, you can for example use them in a non-delayed loop without creating any specific problem for the API.
The Yoctopuce VIs can be used in a non-delayed loop
Note that the YRegisterHub VI is not inside the loop. The YRegisterHub VI is used to initialize the API. Unless you have several URLs that you need to register, it is better to call the YRegisterHub VI only once.
When the name parameter is initialized to an empty string, the Yoctopuce VIs automatically look for a function they can work with. This is very handy when you know that there is only one function of the same type available and when you do not want to manage its name. If the name parameter contains a hardware name or a logical name, the VI looks for the corresponding function. If it does not find it, it emulates an offline function while it waits for the true function to become available.
Using names to identify the functions to be used
The LabVIEW Yoctopuce API is coded to handle errors as smoothly as possible: for example, if you use a VI to access a function which does not exist, the isOnline output is set to FALSE, the other outputs are set to NaN, and thus the inputs do not have any impact. Fatal errors are propagated through the traditional error in, error out channel.
However, the YRegisterHub VI manages connection errors slightly differently. In order to make them easier to manage, connection errors are signaled with Success and error msg outputs. If there is an issue during a call to the YRegisterHub VI, Success contains FALSE and error msg contains a description of the error.
Error handling
The most common error message is "Another process is already using yAPI". It means that another application, LabVIEW or other, already uses the API in native USB mode. For technical reasons, the native USB API can be used by only one application at the same time on the same machine. You can easily work around this limitation by using the network mode.
The Yoctopuce API contains hundreds of methods, functions, and properties. It was not possible, or desirable, to create a VI for each of them. Therefore, there is a VI per class that shows the two properties that Yoctopuce deemed the most useful, but this does not mean that the rest is not available.
Each VI corresponding to a class has two connectors create ref and optional ref which enable you to obtain a reference on the Proxy object of the .NET Proxy API on which the LabVIEW library is built.
The connectors to obtain a reference on the Proxy object corresponding to the VI
To obtain this reference, you only need to set optional ref to TRUE. Note, it is essential to close all references created in this way, otherwise you risk to quickly saturate the computer memory.
Here is an example which uses this technique to change the luminosity of the leds of a Yoctopuce module.
Regulating the luminosity of the leds of a module
Note that each reference allows you to obtain properties (property nodes) as well as methods (invoke nodes). By convention, properties are optimized to generate a minimum of communication with the modules. Therefore, we recommend to use them rather than the corresponding get_xxx and set_xxx methods which might seem equivalent but which are not optimized. Properties also enable you to retrieve the various constants of the API, prefixed with the "_" character. For technical reasons, the get_xxx and set_xxx methods are not all available as properties.
Property and Invoke nodes: Using properties, methods and constants
You can find a description of all the available properties, functions, and methods in the documentation of the .NET Proxy API.
On a given machine, there can be only one process accessing local Yoctopuce modules directly by USB (url set to "usb"). It is however possible that multiple process connect in parallel to YoctoHubs35 or tp a machine on which VirtualHub36 is running, including the local machine. Therefore, if you use the local address of your machine (127.0.0.1) and if a VirtualHub runs on it, you can work around the limitation which prevents using the native USB API in parallel.
Network mode
In the same way, there is no limitation on the number of network interfaces to which the API can connect itself in parallel. This means that it is quite possible to make multiple calls to the YRegisterHub VI. This is the only case where it is useful to call the YRegisterHub VI several times in the life of the application.
You can have multiple network connections
By default, the YRegisterHub VI tries to connect itself on the address given as parameter and generates an error (success=FALSE) when it cannot do so because nobody answers. But if the async parameter is initialized to TRUE, no error is generated when the connection does not succeed. If the connection becomes possible later in the life of the application, the corresponding modules are automatically made available.
Asynchronous connection
Almost all the Yoctopuce sensors have a data logger which enables you to store the measures of the sensors in the non-volatile memory of the module. You can configure the data logger with the VirtualHub, but also with a little bit of LabVIEW code.
To do so, you must configure the logging frequency by using the "LogFrequency" property which you can reach with a reference on the Proxy object of the sensor you are using. Then, you must turn the data logger on thanks to the YDataLogger VI. Note that, like with the YModule VI, you can obtain the YDataLogger VI corresponding to a module with its own name, but also with the name of any of the functions available on the same module.
Activating the data logger
You can retrieve the data in the data logger with the YDataLoggerContents VI.
The YDataLoggerContents VI
Retrieving the data from the logger of a Yoctopuce module is a slow process which can take up to several tens of seconds. Therefore, we designed the VI enabling this operation to work iteratively.
As a first step, you must call the VI with a sensor name, a start date, and an end date (UTC UNIX timestamp). The (0,0) pair enables you to obtain the complete content of the data logger. This first call enables you to obtain a summary of the data logger content and a context.
As a second step, you must call the YDataLoggerContents VI in a loop with the context parameter, until the progress output reaches the 100 value. At this time, the data output represents the content of the data logger.
Retrieving the content of the data logger
The results and the summary are returned as an array of structures containing the following fields:
Note that if the logging frequency is superior to 1Hz, the data logger stores only current values. In this case, averageValue, minValue, and maxValue share the same value.
Each VI corresponding to an object of the Proxy API enables you to list all the functions of the same class with the getSimilarfunctions() method of the corresponding Proxy object. Thus, you can easily perform an inventory of all the connected modules, of all the connected sensors, of all the connected relays, and so on.
Retrieving the list of all the modules which are connected
The LabVIEW Yoctopuce API is optimized so that all the VIs and .NET Proxy API object properties generate a minimum of communication with Yoctopuce modules. Thus, you can use them in loops without taking any specific precaution: you do not have to slow down the loops with a timer.
These two loops generate little USB communication and do not need to be slowed down
However, almost all the methods of the available Proxy objects initiate a communication with the Yoctopuce modules each time they are called. You should therefore avoid calling them too often without purpose.
This loop, using a method, must be slowed down
Here is a short example of how to use the Yocto-MaxiBuzzer in LabVIEW. After a call to the RegisterHub VI, the YBuzzer VI finds the first available buzzer , then use the YModule VI to find out the device serial number. This number is used to build the name of all functions present on the device. Theses names are used to initialize one VI per function. This technique avoids ambiguities when several Yocto-MaxiBuzzer are connected at the same time. Once every VI are initialized, they can be controlled with a few GUI elements. When the application is about to exit, it frees the Yoctopuce API, thanks to the YFreeAPI VI.
Example of Yocto-MaxiBuzzer usage in LabVIEW
If you read this documentation on screen, you can zoom on the image above. You can also find this example in the LabVIEW Yoctopuce library.
Yoctopuce does everything it can to maintain a strong coherence between its different programming libraries. However, LabVIEW being clearly apart as an environment, there are, as a consequence, important differences from the other libraries.
These differences were introduced to make the use of modules as easy as possible and requiring a minimum of LabVIEW code.
In the opposite to other languages, you must absolutely free the native API by calling the YFreeAPI VI when your code does not need to use the API anymore. If you forget this call, the native API risks to stay locked for the other applications until LabVIEW is completely closed.
In the opposite to classes of the other APIs, classes available in LabVIEW implement properties. By convention, these properties are optimized to generate a minimum of communication with the modules while automatically refreshing. By contrast, methods of type get_xxx and set_xxx systematically generate communications with the Yoctopuce modules and must be called sparingly.
There is no callback in the LabVIEW Yoctopuce API, the VIs automatically refresh: they are based on the properties of the .NET Proxy API objects.
Java is an object oriented language created by Sun Microsystem. Beside being free, its main strength is its portability. Unfortunately, this portability has an excruciating price. In Java, hardware abstraction is so high that it is almost impossible to work directly with the hardware. Therefore, the Yoctopuce API does not support native mode in regular Java. The Java API needs a Virtual Hub to communicate with Yoctopuce devices.
Go to the Yoctopuce web site and download the following items:
The library is available as source files as well as a jar file. Decompress the library files in a folder of your choice, connect your modules, run the VirtualHub software, and you are ready to start your first tests. You do not need to install any driver.
In order to keep them simple, all the examples provided in this documentation are console applications. Naturally, the libraries function in a strictly identical manner if you integrate them in an application with a graphical interface.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a Java code snippet to use the Buzzer function.
Let us look at these lines in more details.
The yAPI.RegisterHub function initializes the Yoctopuce API and indicates where the modules should be looked for. The parameter is the address of the Virtual Hub able to see the devices. If the initialization does not succeed, an exception is thrown.
The YBuzzer.FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer.FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch you Java environment and open the corresponding sample project provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library.
In this example, you will recognize the functions explained above, but this time used with all the side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type YModule.get_xxxx(), and properties which are not read-only can be modified with the help of the YModule.set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding YModule.set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the YModule.saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the YModule.revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the YModule.saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the YModule.yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not null. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software.
In the Java API, error handling is implemented with exceptions. Therefore you must catch and handle correctly all exceptions that might be thrown by the API if you do not want your software to crash as soon as you unplug a device.
To tell the truth, Android is not a programming language, it is an operating system developed by Google for mobile appliances such as smart phones and tablets. But it so happens that under Android everything is programmed with the same programming language: Java. Nevertheless, the programming paradigms and the possibilities to access the hardware are slightly different from classical Java, and this justifies a separate chapter on Android programming.
In the opposite to the classical Java API, the Java for Android API can access USB modules natively. However, as there is no VirtualHub running under Android, it is not possible to remotely control Yoctopuce modules connected to a machine under Android. Naturally, the Java for Android API remains perfectly able to connect itself to a VirtualHub running on another OS.
Go to the Yoctopuce web site and download the Java for Android programming library39. The library is available as source files, and also as a jar file. Connect your modules, decompress the library files in the directory of your choice, and configure your Android programming environment so that it can find them.
To keep them simple, all the examples provided in this documentation are snippets of Android applications. You must integrate them in your own Android applications to make them work. However, your can find complete applications in the examples provided with the Java for Android library.
In an ideal world, you would only need to have a smart phone running under Android to be able to make Yoctopuce modules work. Unfortunately, it is not quite so in the real world. A machine running under Android must fulfil to a few requirements to be able to manage Yoctopuce USB modules natively.
Android 4.0 (api 14) and following are officially supported. Theoretically, support of USB host functions since Android 3.1. But be aware that the Yoctopuce Java for Android API is regularly tested only from Android 4 onwards.
Naturally, not only must your machine have a USB port, this port must also be able to run in host mode. In host mode, the machine literally takes control of the devices which are connected to it. The USB ports of a desktop computer, for example, work in host mode. The opposite of the host mode is the device mode. USB keys, for instance, work in device mode: they must be controlled by a host. Some USB ports are able to work in both modes, they are OTG (On The Go) ports. It so happens that many mobile devices can only work in device mode: they are designed to be connected to a charger or a desktop computer, and nothing else. It is therefore highly recommended to pay careful attention to the technical specifications of a product working under Android before hoping to make Yoctopuce modules work with it.
Unfortunately, having a correct version of Android and USB ports working in host mode is not enough to guaranty that Yoctopuce modules will work well under Android. Indeed, some manufacturers configure their Android image so that devices other than keyboard and mass storage are ignored, and this configuration is hard to detect. As things currently stand, the best way to know if a given Android machine works with Yoctopuce modules consists in trying.
The library is tested and validated on the following machines:
If your Android machine is not able to control Yoctopuce modules natively, you still have the possibility to remotely control modules driven by a VirtualHub on another OS, or a YoctoHub 40.
By default, Android does not allow an application to access the devices connected to the USB port. To enable your application to interact with a Yoctopuce module directly connected on your tablet on a USB port, a few additional steps are required. If you intend to interact only with modules connected on another machine through the network, you can ignore this section.
In your AndroidManifest.xml, you must declare using the "USB Host" functionality by adding the <uses-feature android:name="android.hardware.usb.host" /> tag in the manifest section.
When first accessing a Yoctopuce module, Android opens a window to inform the user that the application is going to access the connected module. The user can deny or authorize access to the device. If the user authorizes the access, the application can access the connected device as long as it stays connected. To enable the Yoctopuce library to correctly manage these authorizations, your must provide a pointer on the application context by calling the EnableUSBHost method of the YAPI class before the first USB access. This function takes as arguments an object of the android.content.Context class (or of a subclass). As the Activity class is a subclass of Context, it is simpler to call YAPI.EnableUSBHost(this); in the method onCreate of your application. If the object passed as parameter is not of the correct type, a YAPI_Exception exception is generated.
It is possible to register your application as a default application for a USB module. In this case, as soon as a module is connected to the system, the application is automatically launched. You must add <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"/> in the section <intent-filter> of the main activity. The section <activity> must have a pointer to an XML file containing the list of USB modules which can run the application.
The XML file containing the list of modules allowed to run the application must be saved in the res/xml directory. This file contains a list of USB vendorId and deviceID in decimal. The following example runs the application as soon as a Yocto-Relay or a YoctoPowerRelay is connected. You can find the vendorID and the deviceID of Yoctopuce modules in the characteristics section of the documentation.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a Java code snippet to use the Buzzer function.
Let us look at these lines in more details.
The YAPI.EnableUSBHost function initializes the API with the Context of the current application. This function takes as argument an object of the android.content.Context class (or of a subclass). If you intend to connect your application only to other machines through the network, this function is facultative.
The yAPI.RegisterHub function initializes the Yoctopuce API and indicates where the modules should be looked for. The parameter is the address of the virtual hub able to see the devices. If the string "usb" is passed as parameter, the API works with modules locally connected to the machine. If the initialization does not succeed, an exception is thrown.
The YBuzzer.FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer.FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch you Java environment and open the corresponding sample project provided in the directory Examples//Doc-Examples of the Yoctopuce library.
In this example, you can recognize the functions explained above, but this time used with all the side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type YModule.get_xxxx(), and properties which are not read-only can be modified with the help of the YModule.set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding YModule.set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the YModule.saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the YModule.revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the YModule.saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the YModule.yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not null. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software.
In the Java API for Android, error handling is implemented with exceptions. Therefore you must catch and handle correctly all exceptions that might be thrown by the API if you do not want your software to crash soon as you unplug a device.
TypeScript is an enhanced version of the JavaScript programming language. It is a syntaxic superset with strong typing, therefore increasing the code reliability, but transpiled - aka compiled - into JavaScript for execution in any standard Web browser or Node.js environment.
This Yoctopuce library therefore makes it possible to implement JavaScript applications using strong typing. Similarly to our EcmaScript library, it uses the new asynchronous features introduced in ECMAScript 2017, which are now available in all modern JavaScript environments. Note however that at the time of writting, Web browsers and Node.JS cannot use TypeScript code directly, so you must first compile your TypeScript into JavaScript before running it.
The library works both in a Web browser and in Node.js. In order to allow for a static resolution of dependencies, and to avoid ambiguities that can arise when using hybrid environments such as Electron, the choice of the runtime environment must be done explicitly upon import of the library, by referencing in the project either yocto_api_nodejs.js or yocto_api_html.js.
The library can be integrated in your projects in multiple ways, depending on what best fits your requirements:
1. Start by installing TypeScript on your machine if this is not yet done. In order to do so:
2. Go to the Yoctopuce web site and download the following items:
3. Extract the library files in a folder of your choice, and open a command window in the directory where you have installed it. In order to install the few dependencies which are necessary to start the examples, run this command:
When the command has run without error, you are ready to explore the examples. They are available in two different trees, depending on the environment that you need to use: example_html for running the Yoctopuce library within a Web browser, or example_nodejs if you plan to use the library in a Node.js environment.
The method to use for launching the examples depends on the environment. You will find more about it below.
JavaScript is single-threaded by design. In order to handle time-consuming I/O operations, JavaScript relies on asynchronous operations: the I/O call is only triggered but then the code execution flow is suspended. The JavaScript engine is therefore free to handle other pending tasks, such as user interface. Whenever the pending I/O call is completed, the system invokes a callback function with the result of the I/O call to resume execution of the original execution flow.
When used with plain callback functions, as pervasive in Node.js libraries, asynchronous I/O tend to produce code with poor readability, as the execution flow is broken into many disconnected callback functions. Fortunately, the ECMAScript 2015 standard came in with Promise objects and a new async / await syntax to abstract calls to asynchronous calls:
To make a long story short, async and await make it possible to write TypeScript code with all the benefits of asynchronous I/O, but without breaking the code flow. It is almost like multi-threaded execution, except that control switch between pending tasks only happens at places where the await keyword appears.
This TypeScript library uses the Promise objects and async methods, to allow you to use the await syntax. To keep it easy to remember, all public methods of the TypeScript library are async, i.e. return a Promise object, except:
In most cases, TypeScript strong typing will remind you to use await when calling an asynchronous method.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a TypeScript code snipplet to use the Buzzer function.
Let us look at these lines in more details.
These two imports provide access to functions allowing you to manage Yoctopuce modules. yocto_api is always needed, yocto_buzzer is necessary to manage modules containing a buzzer, such as Yocto-MaxiBuzzer. Other imports can be useful in other cases, such as YModule which can let you enumerate any type of Yoctopuce device.
In order to properly bind yocto_api to the proper network libraries (provided either by Node.js or by the web browser for an HTML application), you must import at least once in your project one of the two variants yocto_api_nodejs.js or yocto_api_html.js.
Note that this example imports the Yoctopuce library as a CommonJS module, which is the most frequently used with Node.JS, but if your project is designed around EcmaScript native modules, you can also replace in the import directive the prefix yoctolib-cjs by yoctolib-esm.
The RegisterHub method allows you to indicate on which machine the Yoctopuce modules are located, more precisely on which machine the VirtualHub software is running. In our case, the 127.0.0.1:4444 address indicates the local machine, port 4444 (the standard port used by Yoctopuce). You can very well modify this address, and enter the address of another machine on which the VirtualHub software is running, or of a YoctoHub. If the host cannot be reached, this function will trigger an exception.
As explained above, using RegisterHub("usb") is not supported in TypeScript, because the JavaScript engine has no direct access to USB devices. It needs to go through the VirtualHub via a localhost connection.
The FindBuzzer method allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can also use logical names, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Open a command window (a terminal, a shell...) and go into the directory example_nodejs/Doc-GettingStarted-Yocto-MaxiBuzzer within Yoctopuce library for TypeScript. In there, you will find a file named demo.ts with the sample code below, which uses the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
If your Yocto-MaxiBuzzer is not connected on the host running the browser, replace in the example the address 127.0.0.1 by the IP address of the host on which the Yocto-MaxiBuzzer is connected and where you run the VirtualHub.
As explained at the beginning of this chapter, you need to have installed the TypeScript compiler on your machine to test these examples, and to install the typescript library dependencies. If you have done that, you can now type the following two commands in the example directory, to finalize the resolution of the example-specific dependencies:
You ar now ready to start the sample code with Node.js. The easiest way to do it is to use the following command, replacing the [...] by the arguments that you want to pass to the demo code:
This command, defined in package.json, will first start the TypeScript compiler using the simple tsc command, then run the transpiled code in Node.js.
The compilation uses the parameters specified in the file tsconfig.json, and produces
Note that the package.json file in our examples uses a relative reference to the local copy of the library, to avoid duplicating the library in each example. But of course, for your application, you can refer to the package directly in npm repository, by adding it to your project using the command:
If you want to see how to use the library within a browser rather than with Node.js, switch to the directory example_html/Doc-GettingStarted-Yocto-MaxiBuzzer. You will find there an HTML file named app.html, and a TypeScript file app.ts similar to the code above, but with a few changes since it has to interact through an HTML page rather than through the JavaScript console.
No installation is needed to run this example, as the TypeScript library is referenced using a relative path. However, in order to allow the browser to run the code, the HTML page must be served by a Web server. We therefore provide a simple test server for this purpose, that you can start with the command:
This command will compile the TypeScript sample code, make it available via an HTTP server on port 3000 and open a Web browser on this example. If you change the example source code, the TypeScript compiler will automatically be triggered to update the transpiled code and a simple page reload on the browser will make it possible to test the change.
As for the Node.js example, the compilation process will create a source map file which makes it possible to debug the example code in TypeScript source form within the browser debugger. Note that as of the writing of this document, this works on Chromium-based browsers but not yet in Firefox.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type get_xxxx(), and properties which are not read-only can be modified with the help of the set_xxx() method. For more details regarding the used methods, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding set_xxx() method. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash() method only 100000 times in the life of the module. Make sure you do not call this method within a loop.
Obtaining the list of the connected modules is performed with the YModule.FirstModule() method which returns the first module found. Then, you only need to call the nextModule() method of this object to find the following modules, and this as long as the returned value is not null. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
EcmaScript is the official name of the standardized version of the web-oriented programming language commonly referred to as JavaScript. This Yoctopuce library take advantages of advanced features introduced in EcmaScript 2017. It has therefore been named Library for JavaScript / EcmaScript 2017 to differentiate it from the previous Library for JavaScript, now deprecated in favor of this new version.
This library provides access to Yoctopuce devices for modern JavaScript engines. It can be used within a browser as well as with Node.js. The library will automatically detect upon initialization whether the runtime environment is a browser or a Node.js virtual machine, and use the most appropriate system libraries accordingly.
Asynchronous communication with the devices is handled across the whole library using Promise objects, leveraging the new EcmaScript 2017 async / await non-blocking syntax for asynchronous I/O (see below). This syntax is now available out-of-the-box in most Javascript engines. No transpilation is needed: no Babel, no jspm, just plain Javascript. Here is your favorite engines minimum version needed to run this code. All of them are officially released at the time we write this document.
If you need backward-compatibility with older releases, you can always run Babel to transpile your code and the library to older standards, as described a few paragraphs below.
We don't suggest using jspm anymore now that async / await are part of the standard.
JavaScript is single-threaded by design. That means, if a program is actively waiting for the result of a network-based operation such as reading from a sensor, the whole program is blocked. In browser environments, this can even completely freeze the user interface. For this reason, the use of blocking I/O in JavaScript is strongly discouraged nowadays, and blocking network APIs are getting deprecated everywhere.
Instead of using parallel threads, JavaScript relies on asynchronous I/O to handle operations with a possible long timeout: whenever a long I/O call needs to be performed, it is only triggered and but then the code execution flow is terminated. The JavaScript engine is therefore free to handle other pending tasks, such as UI. Whenever the pending I/O call is completed, the system invokes a callback function with the result of the I/O call to resume execution of the original execution flow.
When used with plain callback functions, as pervasive in Node.js libraries, asynchronous I/O tend to produce code with poor readability, as the execution flow is broken into many disconnected callback functions. Fortunately, new methods have emerged recently to improve that situation. In particular, the use of Promise objects to abstract and work with asynchronous tasks helps a lot. Any function that makes a long I/O operation can return a Promise, which can be used by the caller to chain subsequent operations in the same flow. Promises are part of EcmaScript 2015 standard.
Promise objects are good, but what makes them even better is the new async / await keywords to handle asynchronous I/O:
Long story made short, async and await make it possible to write EcmaScript code with all benefits of asynchronous I/O, but without breaking the code flow. It is almost like multi-threaded execution, except that control switch between pending tasks only happens at places where the await keyword appears.
We have therefore chosen to write our new EcmaScript library using Promises and async functions, so that you can use the friendly await syntax. To keep it easy to remember, all public methods of the EcmaScript library are async, i.e. return a Promise object, except:
JavaScript is one of those languages which do not generally allow you to directly access the hardware layers of your computer. Therefore the library can only be used to access network-enabled devices (connected through a YoctoHub), or USB devices accessible through Yoctopuce TCP/IP to USB gateway, named VirtualHub.
Go to the Yoctopuce web site and download the following items:
Extract the library files in a folder of your choice, you will find many of examples in it. Connect your modules and start the VirtualHub software. You do not need to install any driver.
Start by installing the latest Node.js version (v7.6 or later) on your system. It is very easy. You can download it from the official web site: http://nodejs.org. Make sure to install it fully, including npm, and add it to the system path.
To give it a try, go into one of the example directory (for instance example_nodejs/Doc-Inventory). You will see that it include an application description file (package.json) and a source file (demo.js). To download and setup the libraries needed by this example, just run:
Once done, you can start the example file using:
If for some reason you need to make changes to the Yoctopuce library, you can easily configure your project to use the local copy in the lib/ subdirectory rather than the official npm package. In order to do so, simply type the following command in your project directory:
For HTML examples, it is even simpler: there is nothing to install. Each example is a single HTML file that you can open in a browser to try it. In this context, loading the Yoctopuce library is no different from any standard HTML script include tag.
If you need to run this library on older JavaScript engines, you can use Babel45 to transpile your code and the library into older JavaScript standards. To install Babel with typical settings, simply use:
You would typically ask Babel to put the transpiled files in another directory, named compat for instance. Your files and all files of the Yoctopuce library should be transpiled, as follow:
Although this approach is based on node.js toolchain, it actually works as well for transpiling JavaScript files for use in a browser. The only thing that you cannot do so easily is transpiling JavaScript code embedded directly in an HTML page. You have to use an external script file for using EcmaScript 2017 syntax with Babel.
Babel has many smart features, such as a watch mode that will automatically refresh transpiled files whenever the source file is changed, but this is beyond the scope of this note. You will find more in Babel documentation.
This new library is not fully backward-compatible with the old JavaScript library, because there is no way to transparently map the old blocking API to the new asynchronous API. The method names however are the same, and old synchronous code can easily be made asynchronous just by adding the proper await keywords before the method calls. For instance, simply replace:
by
Apart from a few exceptions, most XXX_async redundant methods have been removed as well, as they would have introduced confusion on the proper way of handling asynchronous behaviors. It is however very simple to get an async method to invoke a callback upon completion, using the returned Promise object. For instance, you can replace:
by
In some cases, it might be desirable to get a sensor value using a method identical to the old synchronous methods (without using Promises), even if it returns a slightly outdated cached value since I/O is not possible. For this purpose, the EcmaScript library introduce new classes called synchronous proxies. A synchronous proxy is an object that mirrors the most recent state of the connected class, but can be read using regular synchronous function calls. For instance, instead of writing:
you can use:
You can also rewrite this last asynchronous call as:
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a JavaScript code snippet to use the Buzzer function.
Let us look at these lines in more details.
These two import provide access to functions allowing you to manage Yoctopuce modules. yocto_api is always needed, yocto_buzzer is necessary to manage modules containing a buzzer, such as Yocto-MaxiBuzzer. Other imports can be useful in other cases, such as YModule which can let you enumerate any type of Yoctopuce device.
The RegisterHub method allows you to indicate on which machine the Yoctopuce modules are located, more precisely on which machine the VirtualHub software is running. In our case, the 127.0.0.1:4444 address indicates the local machine, port 4444 (the standard port used by Yoctopuce). You can very well modify this address, and enter the address of another machine on which the VirtualHub software is running, or of a YoctoHub. If the host cannot be reached, this function will trigger an exception.
The FindBuzzer method allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can also use logical names, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Open a command window (a terminal, a shell...) and go into the directory example_nodejs/Doc-GettingStarted-Yocto-MaxiBuzzer within Yoctopuce library for JavaScript / EcmaScript 2017. In there, you will find a file named demo.js with the sample code below, which uses the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
If your Yocto-MaxiBuzzer is not connected on the host running the browser, replace in the example the address 127.0.0.1 with the IP address of the host on which the Yocto-MaxiBuzzer is connected and where you run the VirtualHub.
As explained at the beginning of this chapter, you need to have Node.js v7.6 or later installed to try this example. When done, you can type the following two commands to automatically download and install the dependencies for building this example:
If you want to see how to use the library within a browser rather than with Node.js, switch to the directory example_html/Doc-GettingStarted-Yocto-MaxiBuzzer. You will find there a single HTML file, with a JavaScript section similar to the code above, but with a few changes since it has to interact through an HTML page rather than through the JavaScript console.
No installation is needed to run this example, all you have to do is open the HTML file using a web browser,
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type get_xxxx(), and properties which are not read-only can be modified with the help of the set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the YModule.FirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not null. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
PHP is, like Javascript, an atypical language when interfacing with hardware is at stakes. Nevertheless, using PHP with Yoctopuce modules provides you with the opportunity to very easily create web sites which are able to interact with their physical environment, and this is not available to every web server. This technique has a direct application in home automation: a few Yoctopuce modules, a PHP server, and you can interact with your home from anywhere on the planet, as long as you have an internet connection.
PHP is one of those languages which do not allow you to directly access the hardware layers of your computer. Therefore you need to run a virtual hub on the machine on which your modules are connected.
To start your tests with PHP, you need a PHP 5.3 (or more) server46, preferably locally on you machine. If you wish to use the PHP server of your internet provider, it is possible, but you will probably need to configure your ADSL router for it to accept and forward TCP request on the 4444 port.
Go to the Yoctopuce web site and download the following items:
Decompress the library files in a folder of your choice accessible to your web server, connect your modules, run the VirtualHub software, and you are ready to start your first tests. You do not need to install any driver.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a PHP code snipplet to use the Buzzer function.
Let's look at these lines in more details.
These two PHP includes provides access to the functions allowing you to manage Yoctopuce modules. yocto_api.php must always be included, yocto_buzzer.php is necessary to manage modules containing a buzzer, such as Yocto-MaxiBuzzer.
The YAPI::RegisterHub function allows you to indicate on which machine the Yoctopuce modules are located, more precisely on which machine the VirtualHub software is running. In our case, the 127.0.0.1:4444 address indicates the local machine, port 4444 (the standard port used by Yoctopuce). You can very well modify this address, and enter the address of another machine on which the VirtualHub software is running.
The YBuzzer::FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer::FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer::FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by yFindBuzzer sets the buzzer frequency. The parameter is the desired frequency in Hz. A 0Hz frequency will stop the buzzer.
The set_volume() method of the objet returned by yFindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Open your preferred text editor49, copy the code sample below, save it with the Yoctopuce library files in a location which is accessible to you web server, then use your preferred web browser to access this page. The code is also provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library.
In this example, you will recognize the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type get_xxxx(), and properties which are not read-only can be modified with the help of the set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not NULL. Below a short example listing the connected modules.
The PHP library is able to work in a specific mode called HTTP callback Yocto-API. With this mode, you can control Yoctopuce devices installed behind a NAT filter, such as a DSL router for example, and this without needing to open a port. The typical application is to control Yoctopuce devices, located on a private network, from a public web site.
A DSL router which translates network addresses (NAT) works somewhat like a private phone switchboard (a PBX): internal extensions can call each other and call the outside; but seen from the outside, there is only one official phone number, that of the switchboard itself. You cannot reach the internal extensions from the outside.
Typical DSL configuration: LAN machines are isolated from
the outside by the DSL router
Transposed to the network, we have the following: appliances connected to your home automation network can communicate with one another using a local IP address (of the 192.168.xxx.yyy type), and contact Internet servers through their public address. However, seen from the outside, you have only one official IP address, assigned to the DSL router only, and you cannot reach your network appliances directly from the outside. It is rather restrictive, but it is a relatively efficient protection against intrusions.
Responses from request from LAN machines are routed.
But requests from the outside are blocked.
Seeing Internet without being seen provides an enormous security advantage. However, this signifies that you cannot, a priori, set up your own web server at home to control a home automation installation from the outside. A solution to this problem, advised by numerous home automation system dealers, consists in providing outside visibility to your home automation server itself, by adding a routing rule in the NAT configuration of the DSL router. The issue of this solution is that it exposes the home automation server to external attacks.
The HTTP callback API solves this issue without having to modify the DSL router configuration. The module control script is located on an external site, and it is the VirtualHub which is in charge of calling it a regular intervals.
The HTTP callback API uses the VirtualHub which initiates the requests.
The callback API thus uses the VirtualHub as a gateway. All the communications are initiated by the VirtualHub. They are thus outgoing communications and therefore perfectly authorized by the DSL router.
You must configure the VirtualHub so that it calls the PHP script on a regular basis. To do so:
Click on the "configure" button on the first line
Click on the "edit" button of the "Outgoing callbacks" section
And select "Yocto-API callback".
You then only need to define the URL of the PHP script and, if need be, the user name and password to access this URL. Supported authentication methods are basic and digest. The second method is safer than the first one because it does not allow transfer of the password on the network.
From the programmer standpoint, the only difference is at the level of the yRegisterHub function call. Instead of using an IP address, you must use the callback string (or http://callback which is equivalent).
The remainder of the code stays strictly identical. On the VirtualHub interface, at the bottom of the configuration window for the HTTP callback API , there is a button allowing you to test the call to the PHP script.
Be aware that the PHP script controlling the modules remotely through the HTTP callback API can be called only by the VirtualHub. Indeed, it requires the information posted by the VirtualHub to function. To code a web site which controls Yoctopuce modules interactively, you must create a user interface which stores in a file or in a database the actions to be performed on the Yoctopuce modules. These actions are then read and run by the control script.
For the HTTP callback API to work, the PHP option allow_url_fopen
must be set. Some web site hosts do not set it by default.
The problem then manifests itself with the following error:
error: URL file-access is disabled in the server configuration
To set this option, you must create, in the repertory where the
control PHP script is located, an .htaccess file containing the
following line:
php_flag "allow_url_fopen" "On"
Depending on the security policies of the host, it is sometimes impossible
to authorize this option at the root of the web site, or even to
install PHP scripts receiving data from a POST HTTP. In this case, place
the PHP script in a subdirectory.
This method that allows you to go through NAT filters cheaply has nevertheless a price. Communications being initiated by the VirtualHub at a more or less regular interval, reaction time to an event is clearly longer than if the Yoctopuce modules were driven directly. You can configure the reaction time in the specific window of the VirtualHub, but it is at least of a few seconds in the best case.
The HTTP callback Yocto-API mode is currently available in PHP, EcmaScript (Node.JS) and Java only.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
VisualBasic has long been the most favored entrance path to the Microsoft world. Therefore, we had to provide our library for this language, even if the new trend is shifting to C#. All the examples and the project models are tested with Microsoft VisualBasic 2010 Express, freely available on the Microsoft web site50.
Download the Visual Basic Yoctopuce library from the Yoctopuce web site51. There is no setup program, simply copy the content of the zip file into the directory of your choice. You mostly need the content of the Sources directory. The other directories contain the documentation and a few sample programs. All sample projects are Visual Basic 2010, projects, if you are using a previous version, you may have to recreate the projects structure from scratch.
The Visual Basic.NET Yoctopuce library is composed of a DLL and of source files in Visual Basic. The DLL is not a .NET DLL, but a classic DLL, written in C, which manages the low level communications with the modules52. The source files in Visual Basic manage the high level part of the API. Therefore, your need both this DLL and the .vb files of the sources directory to create a project managing Yoctopuce modules.
The following indications are provided for Visual Studio Express 2010, but the process is similar for other versions. Start by creating your project. Then, on the Solution Explorer panel, right click on your project, and select "Add" and then "Add an existing item".
A file selection window opens. Select the yocto_api.vb file and the files corresponding to the functions of the Yoctopuce modules that your project is going to manage. If in doubt, select all the files.
You then have the choice between simply adding these files to your project, or to add them as links (the Add button is in fact a scroll-down menu). In the first case, Visual Studio copies the selected files into your project. In the second case, Visual Studio simply keeps a link on the original files. We recommend you to use links, which makes updates of the library much easier.
Then add in the same manner the yapi.dll DLL, located in the Sources/dll directory53. Then, from the Solution Explorer window, right click on the DLL, select Properties and in the Properties panel, set the Copy to output folder to always. You are now ready to use your Yoctopuce modules from Visual Studio.
In order to keep them simple, all the examples provided in this documentation are console applications. Naturally, the libraries function in a strictly identical manner if you integrate them in an application with a graphical interface.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a Visual Basic code snipplet to use the Buzzer function.
Let's look at these lines in more details.
The YAPI.RegisterHub function initializes the Yoctopuce API and indicates where the modules should be looked for. When used with the parameter "usb", it will use the modules locally connected to the computer running the library. If the initialization does not succeed, this function returns a value different from YAPI_SUCCESS and errmsg contains the error message.
The YBuzzer.FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer.FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by yFindBuzzer sets the buzzer frequency. The parameter is the desired frequency in Hz. A 0Hz frequency will stop the buzzer.
The set_volume() method of the objet returned by yFindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch Microsoft VisualBasic and open the corresponding sample project provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library.
In this example, you will recognize the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type get_xxxx(), and properties which are not read-only can be modified with the help of the set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not Nothing. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
Delphi is a descendent of Turbo-Pascal. Originally, Delphi was produced by Borland, Embarcadero now edits it. The strength of this language resides in its ease of use, as anyone with some notions of the Pascal language can develop a Windows application in next to no time. Its only disadvantage is to cost something54.
Delphi libraries are provided not as VCL components, but directly as source files. These files are compatible with most Delphi versions. 55
To keep them simple, all the examples provided in this documentation are console applications. Obviously, the libraries work in a strictly identical way with VCL applications.
You will soon notice that the Delphi API defines many functions which return objects. You do not need to deallocate these objects yourself, the API does it automatically at the end of the application.
Go to the Yoctopuce web site and download the Yoctopuce Delphi libraries56. Uncompress everything in a directory of your choice, add the subdirectory sources in the list of directories of Delphi libraries.57
By default, the Yoctopuce Delphi library uses the yapi.dll DLL, all the applications you will create with Delphi must have access to this DLL. The simplest way to ensure this is to make sure yapi.dll is located in the same directory as the executable file of your application.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a Delphi code snipplet to use the Buzzer function.
Let's look at these lines in more details.
These two units provide access to the functions allowing you to manage Yoctopuce modules. yocto_api must always be used, yocto_buzzer is necessary to manage modules containing a buzzer, such as Yocto-MaxiBuzzer.
The yRegisterHub function initializes the Yoctopuce API and specifies where the modules should be looked for. When used with the parameter 'usb', it will use the modules locally connected to the computer running the library. If the initialization does not succeed, this function returns a value different from YAPI_SUCCESS and errmsg contains the error message.
The yFindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can also use logical names, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
yFindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by yFindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by yFindBuzzer sets the buzzer frequency. The parameter is the desired frequency in Hz. A 0Hz frequency will stop the buzzer.
The set_volume() method of the objet returned by yFindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch your Delphi environment, copy the yapi.dll DLL in a directory, create a new console application in the same directory, and copy-paste the piece of code below:
In this example, you will recognize the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type get_xxxx(), and properties which are not read-only can be modified with the help of the set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not nil. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
Universal Windows Platform (UWP) is not a language per say, but a software platform created by Microsoft. This platform allows you to run a new type of applications: the universal Windows applications. These applications can work on all machines running under Windows 10. This includes computers, tablets, smart phones, XBox One, and also Windows IoT Core.
The Yoctopuce UWP library allows you to use Yoctopuce modules in a universal Windows application and is written in C# in its entirety. You can add it to a Visual Studio 201758 project.
The Universal Windows Platform does not use the Win32 API but only the Windows Runtime API which is available on all the versions of Windows 10 and for any architecture. Thanks to this library, you can use UWP on all the Windows 10 versions, including Windows 10 IoT Core.
However, using the new UWP API has some consequences: the Windows Runtime API to access the USB ports is asynchronous, and therefore the Yoctopuce library must be asynchronous as well. Concretely, the asynchronous methods do not return a result directly but a Task or Task<> object and the result can be obtained later. Fortunately, the C# language, version 6, supports the async and await keywords, which simplifies using these functions enormously. You can thus use asynchronous functions in the same way as traditional functions as long as you respect the following two rules:
For you not to have to wonder wether a function is asynchronous or not, there is the following convention: all the public methods of the UWP library are asynchronous, that is that you must call them with the await keyword, except:
Download the Yoctopuce library for Universal Windows Platform from the Yoctopuce web site59. There is no installation software, simply copy the content of the zip file in a directory of your choice. You essentially need the content of the Sources directory. The other directories contain documentation and a few sample programs. Sample projects are Visual Studio 2017 projects. Visual Studio 2017 is available on the Microsoft web site60.
Start by creating your project. Then, from the Solution Explorer panel right click on your project and select Add then Existing element .
A file chooser opens: select all the files in the library Sources directory.
You then have the choice between simply adding the files to your project or adding them as a link (the Add button is actually a drop-down menu). In the first case, Visual Studio copies the selected files into your project. In the second case, Visual Studio simply creates a link to the original files. We recommend to use links, as a potential library update is thus much easier.
By default a Universal Windows application doesn't have access rights to the USB ports. If you want to access USB devices, you must imperatively declare it in the Package.appxmanifest file.
Unfortunately, the edition window of this file doesn't allow this operation and you must modify the Package.appxmanifest file by hand. In the "Solution Explorer" panel, right click on the Package.appxmanifest and select "View Code".
In this XML file, we must add a DeviceCapability node in the Capabilities node. This node must have a "Name" attribute with a "humaninterfacedevice" value.
Inside this node, you must declare all the modules that can be used. Concretely, for each module, you must add a "Device" node with an "Id" attribute, which has for value a character string "vidpid:USB_VENDORID USB_DEVICE_ID". The Yoctopuce USB_VENDORID is 24e0 and you can find the USB_DEVICE_ID of each Yoctopuce device in the documentation in the "Characteristics" section. Finally, the "Device" node must contain a "Function" node with the "Type" attribute with a value of "usage:ff00 0001".
For the Yocto-MaxiBuzzer, here is what you must add in the "Capabilities" node:
Unfortunately, it's not possible to write a rule authorizing all Yoctopuce modules. Therefore, you must imperatively add each module that you want to use.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a C# code snippet to use the Buzzer function.
Let us look at these lines in more details.
The YAPI.RegisterHub function initializes the Yoctopuce API and indicates where the modules should be looked for. The parameter is the address of the virtual hub able to see the devices. If the string "usb" is passed as parameter, the API works with modules locally connected to the machine. If the initialization does not succeed, an exception is thrown.
The YBuzzer.FindBuzzer function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
YBuzzer.FindBuzzer returns an object which you can then use at will to control the buzzer.
The isOnline() method of the object returned by YBuzzer.FindBuzzer allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch Visual Studio and open the corresponding project provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library.
Visual Studio projects contain numerous files, and most of them are not linked to the use of the Yoctopuce library. To simplify reading the code, we regrouped all the code that uses the library in the Demo class, located in the demo.cs file. Properties of this class correspond to the different fields displayed on the screen, and the Run() method contains the code which is run when the "Start" button is pushed.
In this example, you can recognize the functions explained above, but this time used with all the side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type YModule.get_xxxx(), and properties which are not read-only can be modified with the help of the YModule.set_xxx() method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding YModule.set_xxx() function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the YModule.saveToFlash() method. Inversely, it is possible to force the module to forget its current settings by using the YModule.revertFromFlash() method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the YModule.saveToFlash() function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the YModule.yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not null. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software.
In the Universal Windows Platform library, error handling is implemented with exceptions. You must therefore intercept and correctly handle these exceptions if you want to have a reliable project which does not crash as soon as you disconnect a module.
Library thrown exceptions are always of the YAPI_Exception type, so you can easily separate them from other exceptions in a try{...} catch{...} block.
Example:
Objective-C is language of choice for programming on Mac OS X, due to its integration with the Cocoa framework. In order to use the Objective-C library, you need XCode version 4.2 (earlier versions will not work), available freely when you run Lion. If you are still under Snow Leopard, you need to be registered as Apple developer to be able to download XCode 4.2. The Yoctopuce library is ARC compatible. You can therefore implement your projects either using the traditional retain / release method, or using the Automatic Reference Counting.
Yoctopuce Objective-C libraries61 are integrally provided as source files. A section of the low-level library is written in pure C, but you should not need to interact directly with it: everything was done to ensure the simplest possible interaction from Objective-C.
You will soon notice that the Objective-C API defines many functions which return objects. You do not need to deallocate these objects yourself, the API does it automatically at the end of the application.
In order to keep them simple, all the examples provided in this documentation are console applications. Naturally, the libraries function in a strictly identical manner if you integrate them in an application with a graphical interface. You can find on Yoctopuce blog a detailed example62 with video shots showing how to integrate the library into your projects.
A few lines of code are enough to use a Yocto-MaxiBuzzer. Here is the skeleton of a Objective-C code snipplet to use the Buzzer function.
Let's look at these lines in more details.
These two import files provide access to the functions allowing you to manage Yoctopuce modules. yocto_api.h must always be used, yocto_buzzer.h is necessary to manage modules containing a buzzer, such as Yocto-MaxiBuzzer.
The [YAPI RegisterHub] function initializes the Yoctopuce API and indicates where the modules should be looked for. When used with the parameter @"usb", it will use the modules locally connected to the computer running the library. If the initialization does not succeed, this function returns a value different from YAPI_SUCCESS and errmsg contains the error message.
The [Buzzer FindBuzzer] function allows you to find a buzzer from the serial number of the module on which it resides and from its function name. You can use logical names as well, as long as you have initialized them. Let us imagine a Yocto-MaxiBuzzer module with serial number YMAXBUZ1-123456 which you have named "MyModule", and for which you have given the buzzer function the name "MyFunction". The following five calls are strictly equivalent, as long as "MyFunction" is defined only once.
[Buzzer FindBuzzer] returns an object which you can then use at will to control the buzzer.
The isOnline method of the object returned by [Buzzer FindBuzzer] allows you to know if the corresponding module is present and in working order.
The set_frequency() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer frequency. The parameter is the frequency in Hz. A 0Hz frequency will stop the buzzer. Handling of Leds and AnButton function works in a similar way.
The set_volume() method of the objet returned by YBuzzer.FindBuzzer sets the buzzer output power. The parameter is the desired volume, between 0 and 100. A volume of 0 will stop the buzzer. When using volume values above 80, make sure the buzzer is not too close to your ear as a tone at full force can be quite painful.
Launch Xcode 4.2 and open the corresponding sample project provided in the directory Examples/Doc-GettingStarted-Yocto-MaxiBuzzer of the Yoctopuce library.
In this example, you will recognize the functions explained above, but this time used with all side materials needed to make it work nicely as a small demo.
Each module can be controlled in a similar manner, you can find below a simple sample program displaying the main parameters of the module and enabling you to activate the localization beacon.
Each property xxx of the module can be read thanks to a method of type get_xxxx, and properties which are not read-only can be modified with the help of the set_xxx: method. For more details regarding the used functions, refer to the API chapters.
When you want to modify the settings of a module, you only need to call the corresponding set_xxx: function. However, this modification is performed only in the random access memory (RAM) of the module: if the module is restarted, the modifications are lost. To memorize them persistently, it is necessary to ask the module to save its current configuration in its permanent memory. To do so, use the saveToFlash method. Inversely, it is possible to force the module to forget its current settings by using the revertFromFlash method. The short example below allows you to modify the logical name of a module.
Warning: the number of write cycles of the nonvolatile memory of the module is limited. When this limit is reached, nothing guaranties that the saving process is performed correctly. This limit, linked to the technology employed by the module micro-processor, is located at about 100000 cycles. In short, you can use the saveToFlash function only 100000 times in the life of the module. Make sure you do not call this function within a loop.
Obtaining the list of the connected modules is performed with the yFirstModule() function which returns the first module found. Then, you only need to call the nextModule() function of this object to find the following modules, and this as long as the returned value is not NULL. Below a short example listing the connected modules.
When you implement a program which must interact with USB modules, you cannot disregard error handling. Inevitably, there will be a time when a user will have unplugged the device, either before running the software, or even while the software is running. The Yoctopuce library is designed to help you support this kind of behavior, but your code must nevertheless be conceived to interpret in the best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this chapter: before accessing a module, check that it is online with the isOnline function, and then hope that it will stay so during the fraction of a second necessary for the following code lines to run. This method is not perfect, but it can be sufficient in some cases. You must however be aware that you cannot completely exclude an error which would occur after the call to isOnline and which could crash the software. The only way to prevent this is to implement one of the two error handling techniques described below.
The method recommended by most programming languages for unpredictable error handling is the use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while you try to access a module, the library throws an exception. In this case, there are three possibilities:
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for error handling, allowing you to create a robust program without needing to catch exceptions at every line of code. You simply need to call the YAPI.DisableExceptions() function to commute the library to a mode where exceptions for all the functions are systematically replaced by specific return values, which can be tested by the caller when necessary. For each function, the name of each return value in case of error is systematically documented in the library reference. The name always follows the same logic: a get_state() method returns a ClassName.STATE_INVALID value, a get_currentValue method returns a ClassName.CURRENTVALUE_INVALID value, and so on. In any case, the returned value is of the expected type and is not a null pointer which would risk crashing your program. At worst, if you display the value without testing it, it will be outside the expected bounds for the returned value. In the case of functions which do not normally return information, the return value is YAPI_SUCCESS if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining the source of the error. You can request them from the object which returned the error, calling the errType() and errMessage() methods. Their returned values contain the same information as in the exceptions when they are active.
Yoctopuce modules can be driven from most common programming languages. New languages are regularly added, depending on the interest expressed by Yoctopuce product users. Nevertheless, some languages are not, and will never be, supported by Yoctopuce. There can be several reasons for this: compilers which are not available anymore, unadapted environments, etc.
However, there are alternative methods to access Yoctopuce modules from an unsupported programming language.
The easiest method to drive Yoctopuce modules from an unsupported programming language is to use the command line API through system calls. The command line API is in fact made of a group of small executables which are easy to call. Their output is also easy to analyze. As most programming languages allow you to make system calls, the issue is solved with a few lines of code.
However, if the command line API is the easiest solution, it is neither the fastest nor the most efficient. For each call, the executable must initialize its own API and make an inventory of USB connected modules. This requires about one second per call.
A .NET Assembly enables you to share a set of pre-compiled classes to offer a service, by stating entry points which can be used by third-party applications. In our case, it's the whole Yoctopuce library which is available in the .NET Assembly, so that it can be used in any environment which supports .NET Assembly dynamic loading.
The Yoctopuce library as a .NET Assembly does not contain only the standard C# Yoctopuce library, as this wouldn't have allowed an optimal use in all environments. Indeed, we cannot expect host applications to necessarily offer a thread system or a callback system, although they are very useful to manage plug-and-play events and sensors with a high refresh rate. Likewise, we can't expect from external applications a transparent behavior in cases where a function call in Assembly creates a delay because of network communications.
Therefore, we added to it an additional layer, called .NET Proxy library. This additional layer offers an interface very similar to the standard library but somewhat simplified, as it internally manages all the callback mechanisms. Instead, this library offers mirror objects, called Proxys, which publish through Properties the main attributes of the Yoctopuce functions such as the current measure, configuration parameters, the state, and so on.
.NET Assembly Architecture
The callback mechanism automatically updates the properties of the Proxys objects, without the host application needing to care for it. The later can thus, at any time and without any risk of latency, display the value of all properties of Yoctopuce Proxy objects.
Pay attention to the fact that the yapi.dll low-level communication library is not included in the .NET Assembly. You must therefore keep it together with DotNetProxyLibrary.dll. The 32 bit version must be located in the same directory as DotNetProxyLibrary.dll, while the 64 bit version must be in a subdirectory amd64.
Here is how to load our Proxy .NET Assembly in MATLAB and how to read the value of the first sensor connected by USB found on the machine:
PowerShell commands are a little stranger, but we can recognize the same structure:
With regards to classic Yoctopuce libraries, the following differences in particular should be noted:
To obtain an object referring to the first found module, we call YModuleProxy.FindModule(""). If there is no connected module, this method returns an object with its module.IsOnline property set to False. As soon as a module is connected, the property changes to True and the module hardware identifier is updated.
To list modules, you can call the module.GetSimilarFunctions() method which returns an array of character strings containing the identifiers of all the modules which were found.
Callback functions are implemented internally and they update the object properties. You can therefore simply poll the properties, without significant performance penalties. Be aware that if you use one of the function that disables callbacks, the automatic refresh of object properties may not work anymore.
A new method YAPIProxy.GetLog makes it possible to retrieve low-level debug logs without using callbacks.
In order to maximize compatibility with host applications, the .NET Proxy library does not use true .NET enumerated types, but simple integers. For each enumerated type, the library includes public constants named according to the possible values. Contrarily to standard Yoctopuce libraries, numeric values always start from 1, as the value 0 is reserved to return an invalid value, for instance when the device is disconnected.
For all numeric results, rather than using an arbitrary constant, the invalid value returned in case of error is NaN. You should therefore use function isNaN() to detect this value.
If for a reason or another you don't want to use the Proxy library, and if your environment allows it, you can use the standard C# API as it is located in the Assembly, under the YoctoLib namespace. Beware however not to mix both types of use: either you go through the Proxy library, or you use he YoctoLib version directly, but not both!
For the LabVIEW Yoctopuce library to work correctly with your Yoctopuce modules, these modules need to have firmware 37120, or higher.
In order to be compatible with as many versions of Windows as possible, including Windows XP, the DotNetProxyLibrary.dll library is compiled in .NET 3.5, which is available by default on all the Windows versions since XP. As of today, we have never met any non-Windows environment able to load a .NET Assembly, so we only ship the low-level communication dll for Windows together with the assembly.
The VirtualHub is available on almost all current platforms. It is generally used as a gateway to provide access to Yoctopuce modules from languages which prevent direct access to hardware layers of a computer (JavaScript, PHP, Java, ...).
In fact, the VirtualHub is a small web server able to route HTTP requests to Yoctopuce modules. This means that if you can make an HTTP request from your programming language, you can drive Yoctopuce modules, even if this language is not officially supported.
At a low level, the modules are driven through a REST API. Thus, to control a module, you only need to perform appropriate requests on the VirtualHub. By default, the VirtualHub HTTP port is 4444.
An important advantage of this technique is that preliminary tests are very easy to implement. You only need a VirtualHub and a simple web browser. If you copy the following URL in your preferred browser, while the VirtualHub is running, you obtain the list of the connected modules.
Note that the result is displayed as text, but if you request whitePages.xml, you obtain an XML result. Likewise, whitePages.json allows you to obtain a JSON result. The html extension even allows you to display a rough interface where you can modify values in real time. The whole REST API is available in these different formats.
Each Yoctopuce module has its own REST interface, available in several variants. Let us imagine a Yocto-MaxiBuzzer with the YMAXBUZ1-12345 serial number and the myModule logical name. The following URL allows you to know the state of the module.
You can naturally also use the module logical name rather than its serial number.
To retrieve the value of a module property, simply add the name of the property below module. For example, if you want to know the signposting led luminosity, send the following request:
To change the value of a property, modify the corresponding attribute. Thus, to modify the luminosity, send the following request:
The module functions can be manipulated in the same way. To know the state of the buzzer function, build the following URL:
Note that if you can use logical names for the modules instead of their serial number, you cannot use logical names for functions. Only hardware names are authorized to access functions.
You can retrieve a module function attribute in a way rather similar to that used with the modules. For example:
Rather logically, attributes can be modified in the same manner.
You can find the list of available attributes for your Yocto-MaxiBuzzer at the beginning of the Programming chapter.
This section only applies to devices with a built-in data logger.
The preview of all recorded data streams can be retrieved in JSON format using the following URL:
Individual measures for any given stream can be obtained by appending the desired function identifier as well as start time of the stream:
The low level Yoctopuce API is available under several formats of dynamic libraries written in C. The sources are available with the C++ API. If you use one of these low level libraries, you do not need the VirtualHub anymore.
Filename | Platform |
---|---|
libyapi.dylib | Max OS X |
libyapi-amd64.so | Linux Intel (64 bits) |
libyapi-armel.so | Linux ARM EL (32 bits) |
libyapi-armhf.so | Linux ARM HL (32 bits) |
libyapi-aarch64.so | Linux ARM (64 bits) |
libyapi-i386.so | Linux Intel (32 bits) |
yapi64.dll | Windows (64 bits) |
yapi.dll | Windows (32 bits) |
These dynamic libraries contain all the functions necessary to completely rebuild the whole high level API in any language able to integrate these libraries. This chapter nevertheless restrains itself to describing basic use of the modules.
The three essential functions of the low level API are the following:
The yapiInitAPI function initializes the API and must be called once at the beginning of the program. For a USB type connection, the connection_type parameter takes value 1. The errmsg parameter must point to a 255 character buffer to retrieve a potential error message. This pointer can also point to null. The function returns a negative integer in case of error, zero otherwise.
The yapiUpdateDeviceList manages the inventory of connected Yoctopuce modules. It must be called at least once. To manage hot plug and detect potential newly connected modules, this function must be called at regular intervals. The forceupdate parameter must take value 1 to force a hardware scan. The errmsg parameter must point to a 255 character buffer to retrieve a potential error message. This pointer can also point to null. The function returns a negative integer in case of error, zero otherwise.
Finally, the yapiHTTPRequest function sends HTTP requests to the module REST API. The device parameter contains the serial number or the logical name of the module which you want to reach. The request parameter contains the full HTTP request (including terminal line breaks). buffer points to a character buffer long enough to contain the answer. buffsize is the size of the buffer. fullsize is a pointer to an integer to which will be assigned the actual size of the answer. The errmsg parameter must point to a 255 character buffer to retrieve a potential error message. This pointer can also point to null. The function returns a negative integer in case of error, zero otherwise.
The format of the requests is the same as the one described in the VirtualHub et HTTP GET section. All the character strings used by the API are strings made of 8-bit characters: Unicode and UTF8 are not supported.
The resutlt returned in the buffer variable respects the HTTP protocol. It therefore includes an HTTP header. This header ends with two empty lines, that is a sequence of four ASCII characters 13, 10, 13, 10.
Here is a sample program written in pascal using the yapi.dll DLL to read and then update the luminosity of a module.
To perform an inventory of Yoctopuce modules, you need two functions from the dynamic library:
The yapiGetAllDevices function retrieves the list of all connected modules as a list of handles. buffer points to a 32-bit integer array which contains the returned handles. maxsize is the size in bytes of the buffer. To neededsize is assigned the necessary size to store all the handles. From this, you can deduce either the number of connected modules or that the input buffer is too small. The errmsg parameter must point to a 255 character buffer to retrieve a potential error message. This pointer can also point to null. The function returns a negative integer in case of error, zero otherwise.
The yapiGetDeviceInfo function retrieves the information related to a module from its handle. devdesc is a 32-bit integer representing the module and which was obtained through yapiGetAllDevices. infos points to a data structure in which the result is stored. This data structure has the following format:
Name | Type | Size (bytes) | Description |
---|---|---|---|
vendorid | int | 4 | Yoctopuce USB ID |
deviceid | int | 4 | Module USB ID |
devrelease | int | 4 | Module version |
nbinbterfaces | int | 4 | Number of USB interfaces used by the module |
manufacturer | char[] | 20 | Yoctopuce (null terminated) |
productname | char[] | 28 | Model (null terminated) |
serial | char[] | 20 | Serial number (null terminated) |
logicalname | char[] | 20 | Logical name (null terminated) |
firmware | char[] | 22 | Firmware version (null terminated) |
beacon | byte | 1 | Beacon state (0/1) |
The errmsg parameter must point to a 255 character buffer to retrieve a potential error message.
Here is a sample program written in pascal using the yapi.dll DLL to list the connected modules.
Each entry point from the yapi.dll is duplicated. You will find one regular C-decl version and one Visual Basic 6 compatible version, prefixed with vb6_.
As all the sources of the Yoctopuce API are fully provided, you can very well port the whole API in the language of your choice. Note, however, that a large portion of the API source code is automatically generated.
Therefore, it is not necessary for you to port the complete API. You only need to port the yocto_api file and one file corresponding to a function, for example yocto_relay. After a little additional work, Yoctopuce is then able to generate all other files. Therefore, we highly recommend that you contact Yoctopuce support before undertaking to port the Yoctopuce library in another language. Collaborative work is advantageous to both parties.
The preceding chapters have introduced, in each available language, the basic programming functions which can be used with your Yocto-MaxiBuzzer module. This chapter presents in a more generic manner a more advanced use of your module. Examples are provided in the language which is the most popular among Yoctopuce customers, that is C#. Nevertheless, you can find complete examples illustrating the concepts presented here in the programming libraries of each language.
To remain as concise as possible, examples provided in this chapter do not perform any error handling. Do not copy them "as is" in a production application.
The methods to manage Yoctopuce modules which we presented to you in preceding chapters were polling functions, consisting in permanently asking the API if something had changed. While easy to understand, this programming technique is not the most efficient, nor the most reactive. Therefore, the Yoctopuce programming API also provides an event programming model. This technique consists in asking the API to signal by itself the important changes as soon as they are detected. Each time a key parameter is modified, the API calls a callback function which you have defined in advance.
Hot-plug management is important when you work with USB modules because, sooner or later, you will have to connect or disconnect a module when your application is running. The API is designed to manage module unexpected arrival or departure in a transparent way. But your application must take this into account if it wants to avoid pretending to use a disconnected module.
Event programming is particularly useful to detect module connection/disconnection. Indeed, it is simpler to be told of new connections rather than to have to permanently list the connected modules to deduce which ones just arrived and which ones left. To be warned as soon as a module is connected, you need three pieces of code.
The callback is the function which is called each time a new Yoctopuce module is connected. It takes as parameter the relevant module.
You must then tell the API that it must call the callback when a new module is connected.
Note that if modules are already connected when the callback is registered, the callback is called for each of the already connected modules.
A classis issue of callback programming is that these callbacks can be triggered at any time, including at times when the main program is not ready to receive them. This can have undesired side effects, such as dead-locks and other race conditions. Therefore, in the Yoctopuce API, module arrival/departure callbacks are called only when the UpdateDeviceList() function is running. You only need to call UpdateDeviceList() at regular intervals from a timer or from a specific thread to precisely control when the calls to these callbacks happen:
In a similar way, it is possible to have a callback when a module is disconnected. You can find a complete example implemented in your favorite programming language in the Examples/Prog-EventBased directory of the corresponding library.
Be aware that in most programming languages, callbacks must be global procedures, and not methods. If you wish for the callback to call the method of an object, define your callback as a global procedure which then calls your method.
It is possible to update the firmware directly from the web interface of the VirtualHub or the YoctoHub. The configuration panel of the module has an "upgrade" button to start a wizard that will guide you through the firmware update procedure.
In case the firmware update fails for any reason, and the module does no start anymore, simply unplug the module then plug it back while maintaining the Yocto-button down. The module will boot in "firmware update" mode and will appear in the VirtualHub interface below the module list.
All the command line tools can update Yoctopuce modules thanks to the downloadAndUpdate command. The module selection mechanism works like for a traditional command. The [target] is the name of the module that you want to update. You can also use the "any" or "all" aliases, or even a name list, where the names are separated by commas, without spaces.
The following example updates all the Yoctopuce modules connected by USB.
You can update your module firmware from your Android phone or tablet with the Yocto-Firmware application. This application lists all the Yoctopuce modules connected by USB and checks if a more recent firmware is available on www.yoctopuce.com. If a more recent firmware is available, you can update the module. The application is responsible for downloading and installing the new firmware while preserving the module parameters.
Please note: while the firmware is being updated, the module restarts several times. Android interprets a USB device reboot as a disconnection and reconnection of the USB device and asks the authorization to use the USB port again. The user must click on OK for the update process to end successfully.
If you need to integrate firmware updates in your application, the libraries offer you an API to update your modules. 63
The get_allSettings() method returns a binary buffer enabling you to save a module persistent parameters. This function is very useful to save the network configuration of a YoctoHub for example.
You can then apply these parameters to other modules with the set_allSettings() method.
The first step to update a Yoctopuce module is to find which firmware you must use. The checkFirmware(path, onlynew) method of the YModule object does exactly this. The method checks that the firmware given as argument (path) is compatible with the module. If the onlynew parameter is set, this method checks that the firmware is more recent than the version currently used by the module. When the file is not compatible (or if the file is older than the installed version), this method returns an empty string. In the opposite, if the file is valid, the method returns a file access path.
The following piece of code checks that the c:\tmp\METEOMK1.17328.byn is compatible with the module stored in the m variable .
The argument can be a directory (instead of a file). In this case, the method checks all the files of the directory recursively and returns the most recent compatible firmware. The following piece of code checks whether there is a more recent firmware in the c:\tmp\ directory.
You can also give the "www.yoctopuce.com" string as argument to check whether there is a more recent published firmware on Yoctopuce's web site. In this case, the method returns the firmware URL. You can use this URL to download the firmware on your disk or use this URL when updating the firmware (see below). Obviously, this possibility works only if your machine is connected to Internet.
A firmware update can take several minutes. That is why the update process is run as a background task and is driven by the user code thanks to the YFirmwareUdpate class.
To update a Yoctopuce module, you must obtain an instance of the YFirmwareUdpate class with the updateFirmware method of a YModule object. The only parameter of this method is the path of the firmware that you want to install. This method does not immediately start the update, but returns a YFirmwareUdpate object configured to update the module.
The startUpdate() method starts the update as a background task. This background task automatically takes care of
The get_progress() and get_progressMessage() methods enable you to follow the progression of the update. get_progress() returns the progression as a percentage (100 = update complete). get_progressMessage() returns a character string describing the current operation (deleting, writing, rebooting, ...). If the get_progress method returns a negative value, the update process failed. In this case, the get_progressMessage() returns an error message.
The following piece of code starts the update and displays the progress on the standard output.
You can update a module firmware using the Android library. However, for modules connected by USB, Android asks the user to authorize the application to access the USB port.
During firmware update, the module restarts several times. Android interprets a USB device reboot as a disconnection and a reconnection to the USB port, and prevents all USB access as long as the user has not closed the pop-up window. The use has to click on OK for the update process to continue correctly. You cannot update a module connected by USB to an Android device without having the user interacting with the device.
If you want to erase all the parameters of a module or if your module does not start correctly anymore, you can install a firmware from the "update" mode.
To force the module to work in "update" mode, disconnect it, wait a few seconds, and reconnect it while maintaining the Yocto-button down. This will restart the module in "update" mode. This update mode is protected against corruptions and is always available.
In this mode, the module is not detected by the YModule objects anymore. To obtain the list of connected modules in "update" mode, you must use the YAPI.GetAllBootLoaders() function. This function returns a character string array with the serial numbers of the modules in "update" mode.
The update process is identical to the standard case (see the preceding section), but you must manually instantiate the YFirmwareUpdate object instead of calling module.updateFirmware(). The constructor takes as argument three parameters: the module serial number, the path of the firmware to be installed, and a byte array with the parameters to be restored at the end of the update (or null to restore default parameters).
This chapter summarizes the high-level API functions to drive your Yocto-MaxiBuzzer. Syntax and exact type names may vary from one language to another, but, unless otherwise stated, all the functions are available in every language. For detailed information regarding the types of arguments and return values for a given language, refer to the definition file for this language (yocto_api.* as well as the other yocto_* files that define the function interfaces).
For languages which support exceptions, all of these functions throw exceptions in case of error by default, rather than returning the documented error value for each function. This is by design, to facilitate debugging. It is however possible to disable the use of exceptions using the yDisableExceptions() function, in case you prefer to work with functions that return error values.
This chapter does not repeat the programming concepts described earlier, in order to stay as concise as possible. In case of doubt, do not hesitate to go back to the chapter describing in details all configurable attributes.
General functions
These general functions should be used to initialize and configure the Yoctopuce library. In most cases, a simple call to function yRegisterHub() should be enough. The module-specific functions yFind...() or yFirst...() should then be used to retrieve an object that provides interaction with the module.
In order to use the functions described here, you should include:
java | import com.yoctopuce.YoctoAPI.YAPI; |
dnp | import YoctoProxyAPI.YAPIProxy |
cp | #include "yocto_api_proxy.h" |
ml | import YoctoProxyAPI.YAPIProxy" |
js | <script type='text/javascript' src='yocto_api.js'></script> |
cpp | #include "yocto_api.h" |
m | #import "yocto_api.h" |
pas | uses yocto_api; |
vb | yocto_api.vb |
cs | yocto_api.cs |
uwp | import com.yoctopuce.YoctoAPI.YModule; |
py | from yocto_api import * |
php | require_once('yocto_api.php'); |
ts | in HTML: import { YAPI, YErrorMsg, YModule, YSensor } from '../../dist/esm/yocto_api_browser.js'; in Node.js: import { YAPI, YErrorMsg, YModule, YSensor } from 'yoctolib-cjs/yocto_api_nodejs.js'; |
es | in HTML: <script src="../../lib/yocto_api.js"></script> in node.js: require('yoctolib-es2017/yocto_api.js'); |
vi | YModule.vi |
Global functions |
---|
YAPI.CheckLogicalName(name) |
Checks if a given string is valid as logical name for a module or a function. |
YAPI.ClearHTTPCallbackCacheDir(bool_removeFiles) |
Disables the HTTP callback cache. |
YAPI.DisableExceptions() |
Disables the use of exceptions to report runtime errors. |
YAPI.EnableExceptions() |
Re-enables the use of exceptions for runtime error handling. |
YAPI.EnableUSBHost(osContext) |
This function is used only on Android. |
YAPI.FreeAPI() |
Waits for all pending communications with Yoctopuce devices to be completed then frees dynamically allocated resources used by the Yoctopuce library. |
YAPI.GetAPIVersion() |
Returns the version identifier for the Yoctopuce library in use. |
YAPI.GetCacheValidity() |
Returns the validity period of the data loaded by the library. |
YAPI.GetDeviceListValidity() |
Returns the delay between each forced enumeration of the used YoctoHubs. |
YAPI.GetDllArchitecture() |
Returns the system architecture for the Yoctopuce communication library in use. |
YAPI.GetDllPath() |
Returns the paths of the DLLs for the Yoctopuce library in use. |
YAPI.GetLog(lastLogLine) |
Retrieves Yoctopuce low-level library diagnostic logs. |
YAPI.GetNetworkTimeout() |
Returns the network connection delay for yRegisterHub() and yUpdateDeviceList(). |
YAPI.GetTickCount() |
Returns the current value of a monotone millisecond-based time counter. |
YAPI.HandleEvents(errmsg) |
Maintains the device-to-library communication channel. |
YAPI.InitAPI(mode, errmsg) |
Initializes the Yoctopuce programming library explicitly. |
YAPI.PreregisterHub(url, errmsg) |
Fault-tolerant alternative to yRegisterHub(). |
YAPI.RegisterDeviceArrivalCallback(arrivalCallback) |
Register a callback function, to be called each time a device is plugged. |
YAPI.RegisterDeviceRemovalCallback(removalCallback) |
Register a callback function, to be called each time a device is unplugged. |
YAPI.RegisterHub(url, errmsg) |
Setup the Yoctopuce library to use modules connected on a given machine. |
YAPI.RegisterHubDiscoveryCallback(hubDiscoveryCallback) |
Register a callback function, to be called each time an Network Hub send an SSDP message. |
YAPI.RegisterHubWebsocketCallback(ws, errmsg, authpwd) |
Variant to yRegisterHub() used to initialize Yoctopuce API on an existing Websocket session, as happens for incoming WebSocket callbacks. |
YAPI.RegisterLogFunction(logfun) |
Registers a log callback function. |
YAPI.SelectArchitecture(arch) |
Select the architecture or the library to be loaded to access to USB. |
YAPI.SetCacheValidity(cacheValidityMs) |
Change the validity period of the data loaded by the library. |
YAPI.SetDelegate(object) |
(Objective-C only) Register an object that must follow the protocol YDeviceHotPlug. |
YAPI.SetDeviceListValidity(deviceListValidity) |
Modifies the delay between each forced enumeration of the used YoctoHubs. |
YAPI.SetHTTPCallbackCacheDir(str_directory) |
Enables the HTTP callback cache. |
YAPI.SetNetworkTimeout(networkMsTimeout) |
Modifies the network connection delay for yRegisterHub() and yUpdateDeviceList(). |
YAPI.SetTimeout(callback, ms_timeout, args) |
Invoke the specified callback function after a given timeout. |
YAPI.SetUSBPacketAckMs(pktAckDelay) |
Enables the acknowledge of every USB packet received by the Yoctopuce library. |
YAPI.Sleep(ms_duration, errmsg) |
Pauses the execution flow for a specified duration. |
YAPI.TestHub(url, mstimeout, errmsg) |
Test if the hub is reachable. |
YAPI.TriggerHubDiscovery(errmsg) |
Force a hub discovery, if a callback as been registered with yRegisterHubDiscoveryCallback it will be called for each net work hub that will respond to the discovery. |
YAPI.UnregisterHub(url) |
Setup the Yoctopuce library to no more use modules connected on a previously registered machine with RegisterHub. |
YAPI.UpdateDeviceList(errmsg) |
Triggers a (re)detection of connected Yoctopuce modules. |
YAPI.UpdateDeviceList_async(callback, context) |
Triggers a (re)detection of connected Yoctopuce modules. |
Checks if a given string is valid as logical name for a module or a function.
js | function yCheckLogicalName( | name) |
cpp | bool CheckLogicalName( | string name) |
m | +(BOOL) CheckLogicalName | :(NSString *) name |
pas | boolean yCheckLogicalName( | name: string): boolean |
vb | function CheckLogicalName( | ByVal name As String) As Boolean |
cs | static bool CheckLogicalName( | string name) |
java | boolean CheckLogicalName( | String name) |
uwp | bool CheckLogicalName( | string name) |
py | CheckLogicalName( | name) |
php | function CheckLogicalName( | $name) |
ts | async CheckLogicalName( | name: string): Promise<boolean> |
es | async CheckLogicalName( | name) |
A valid logical name has a maximum of 19 characters, all among A..Z, a..z, 0..9, _, and -. If you try to configure a logical name with an incorrect string, the invalid characters are ignored.
Parameters :
name | a string containing the name to check. |
Returns :
true if the name is valid, false otherwise.
Disables the HTTP callback cache.
php | function ClearHTTPCallbackCacheDir( | $bool_removeFiles) |
This method disables the HTTP callback cache, and can additionally cleanup the cache directory.
Parameters :
bool_removeFiles | True to clear the content of the cache. |
Returns :
nothing.
Disables the use of exceptions to report runtime errors.
js | function yDisableExceptions( | ) |
cpp | void DisableExceptions( | ) |
m | +(void) DisableExceptions |
pas | yDisableExceptions( | ) |
vb | procedure DisableExceptions( | ) |
cs | static void DisableExceptions( | ) |
uwp | void DisableExceptions( | ) |
py | DisableExceptions( | ) |
php | function DisableExceptions( | ) |
ts | async DisableExceptions( | ): Promise<void> |
es | async DisableExceptions( | ) |
When exceptions are disabled, every function returns a specific error value which depends on its type and which is documented in this reference manual.
Re-enables the use of exceptions for runtime error handling.
js | function yEnableExceptions( | ) |
cpp | void EnableExceptions( | ) |
m | +(void) EnableExceptions |
pas | yEnableExceptions( | ) |
vb | procedure EnableExceptions( | ) |
cs | static void EnableExceptions( | ) |
uwp | void EnableExceptions( | ) |
py | EnableExceptions( | ) |
php | function EnableExceptions( | ) |
ts | async EnableExceptions( | ): Promise<void> |
es | async EnableExceptions( | ) |
Be aware than when exceptions are enabled, every function that fails triggers an exception. If the exception is not caught by the user code, it either fires the debugger or aborts (i.e. crash) the program. On failure, throws an exception or returns a negative error code.
This function is used only on Android.
java | void EnableUSBHost( | Object osContext) |
Before calling yRegisterHub("usb") you need to activate the USB host port of the system. This function takes as argument, an object of class android.content.Context (or any subclass). It is not necessary to call this function to reach modules through the network.
Parameters :
osContext | an object of class android.content.Context (or any subclass). |
Waits for all pending communications with Yoctopuce devices to be completed then frees dynamically allocated resources used by the Yoctopuce library.
js | function yFreeAPI( | ) |
cpp | void FreeAPI( | ) |
m | +(void) FreeAPI |
pas | yFreeAPI( | ) |
vb | procedure FreeAPI( | ) |
cs | static void FreeAPI( | ) |
java | void FreeAPI( | ) |
uwp | void FreeAPI( | ) |
py | FreeAPI( | ) |
php | function FreeAPI( | ) |
ts | async FreeAPI( | ): Promise<void> |
es | async FreeAPI( | ) |
dnp | static void FreeAPI( | ) |
cp | static void FreeAPI( | ) |
From an operating system standpoint, it is generally not required to call this function since the OS will automatically free allocated resources once your program is completed. However there are two situations when you may really want to use that function: - Free all dynamically allocated memory blocks in order to track a memory leak. - Send commands to devices right before the end of the program. Since commands are sent in an asynchronous way the program could exit before all commands are effectively sent. You should not call any other library function after calling yFreeAPI(), or your program will crash.
Returns the version identifier for the Yoctopuce library in use.
js | function yGetAPIVersion( | ) |
cpp | string GetAPIVersion( | ) |
m | +(NSString*) GetAPIVersion |
pas | string yGetAPIVersion( | ): string |
vb | function GetAPIVersion( | ) As String |
cs | static String GetAPIVersion( | ) |
java | static String GetAPIVersion( | ) |
uwp | static string GetAPIVersion( | ) |
py | GetAPIVersion( | ) |
php | function GetAPIVersion( | ) |
ts | async GetAPIVersion( | ) |
es | async GetAPIVersion( | ) |
dnp | static string GetAPIVersion( | ) |
cp | static string GetAPIVersion( | ) |
The version is a string in the form "Major.Minor.Build", for instance "1.01.5535". For languages using an external DLL (for instance C#, VisualBasic or Delphi), the character string includes as well the DLL version, for instance "1.01.5535 (1.01.5439)".
If you want to verify in your code that the library version is compatible with the version that you have used during development, verify that the major number is strictly equal and that the minor number is greater or equal. The build number is not relevant with respect to the library compatibility.
Returns :
a character string describing the library version.
Returns the validity period of the data loaded by the library.
cpp | static u64 GetCacheValidity( | ) |
m | +(u64) GetCacheValidity |
pas | u64 yGetCacheValidity( | ): u64 |
vb | function GetCacheValidity( | ) As Long |
cs | ulong GetCacheValidity( | ) |
java | long GetCacheValidity( | ) |
uwp | async Task<ulong> GetCacheValidity( | ) |
py | GetCacheValidity( | ) |
php | function GetCacheValidity( | ) |
ts | async GetCacheValidity( | ): Promise<number> |
es | async GetCacheValidity( | ) |
This method returns the cache validity of all attributes module functions. Note: This function must be called after yInitAPI .
Returns :
an integer corresponding to the validity attributed to the loaded function parameters, in milliseconds
Returns the delay between each forced enumeration of the used YoctoHubs.
cpp | static int GetDeviceListValidity( | ) |
m | +(int) GetDeviceListValidity |
pas | LongInt yGetDeviceListValidity( | ): LongInt |
vb | function GetDeviceListValidity( | ) As Integer |
cs | int GetDeviceListValidity( | ) |
java | int GetDeviceListValidity( | ) |
uwp | async Task<int> GetDeviceListValidity( | ) |
py | GetDeviceListValidity( | ) |
php | function GetDeviceListValidity( | ) |
ts | async GetDeviceListValidity( | ): Promise<number> |
es | async GetDeviceListValidity( | ) |
Note: you must call this function after yInitAPI.
Returns :
the number of seconds between each enumeration.
Returns the system architecture for the Yoctopuce communication library in use.
dnp | static string GetDllArchitecture( | ) |
On Windows, the architecture can be "Win32" or "Win64". On ARM machines, the architecture is "Armhf32" or "Aarch64". On other Linux machines, the architecture is "Linux32" or "Linux64". On MacOS, the architecture is "MacOs32" or "MacOs64".
Returns :
a character string describing the system architecture of the low-level communication library.
Returns the paths of the DLLs for the Yoctopuce library in use.
dnp | static string GetDllPath( | ) |
For architectures that require multiple DLLs, in particular when using a .NET assembly DLL, the returned string takes the form "DotNetProxy=/...; yapi=/...;", where the first path corresponds to the .NET assembly DLL and the second path corresponds to the low-level communication library.
Returns :
a character string describing the DLL path.
Retrieves Yoctopuce low-level library diagnostic logs.
dnp | static string GetLog( | string lastLogLine) |
cp | static string GetLog( | string lastLogLine) |
This method allows to progessively retrieve API logs. The interface is line-based: it must called it within a loop until the returned value is an empty string. Make sure to exit the loop when an empty string is returned, as feeding an empty string into the lastLogLine parameter for the next call would restart enumerating logs from the oldest message available.
Parameters :
lastLogLine | On first call, provide an empty string. On subsequent calls, provide the last log line returned by GetLog(). |
Returns :
a string with the log line immediately following the one given in argument, if such line exist. Returns an empty string otherwise, when completed.
Returns the network connection delay for yRegisterHub() and yUpdateDeviceList().
cpp | static int GetNetworkTimeout( | ) |
m | +(int) GetNetworkTimeout |
pas | LongInt yGetNetworkTimeout( | ): LongInt |
vb | function GetNetworkTimeout( | ) As Integer |
cs | int GetNetworkTimeout( | ) |
java | int GetNetworkTimeout( | ) |
uwp | async Task<int> GetNetworkTimeout( | ) |
py | GetNetworkTimeout( | ) |
php | function GetNetworkTimeout( | ) |
ts | async GetNetworkTimeout( | ): Promise<number> |
es | async GetNetworkTimeout( | ) |
dnp | static int GetNetworkTimeout( | ) |
cp | static int GetNetworkTimeout( | ) |
This delay impacts only the YoctoHubs and VirtualHub which are accessible through the network. By default, this delay is of 20000 milliseconds, but depending or you network you may want to change this delay, for example if your network infrastructure is based on a GSM connection.
Returns :
the network connection delay in milliseconds.
Returns the current value of a monotone millisecond-based time counter.
js | function yGetTickCount( | ) |
cpp | u64 GetTickCount( | ) |
m | +(u64) GetTickCount |
pas | u64 yGetTickCount( | ): u64 |
vb | function GetTickCount( | ) As Long |
cs | static ulong GetTickCount( | ) |
java | static long GetTickCount( | ) |
uwp | static ulong GetTickCount( | ) |
py | GetTickCount( | ) |
php | function GetTickCount( | ) |
ts | GetTickCount( | ): number |
es | GetTickCount( | ) |
This counter can be used to compute delays in relation with Yoctopuce devices, which also uses the millisecond as timebase.
Returns :
a long integer corresponding to the millisecond counter.
Maintains the device-to-library communication channel.
js | function yHandleEvents( | errmsg) |
cpp | YRETCODE HandleEvents( | string errmsg) |
m | +(YRETCODE) HandleEvents | :(NSError**) errmsg |
pas | integer yHandleEvents( | var errmsg: string): integer |
vb | function HandleEvents( | ByRef errmsg As String) As YRETCODE |
cs | static YRETCODE HandleEvents( | ref string errmsg) |
java | int HandleEvents( | ) |
uwp | async Task<int> HandleEvents( | ) |
py | HandleEvents( | errmsg=None) |
php | function HandleEvents( | &$errmsg) |
ts | async HandleEvents( | errmsg: YErrorMsg | null): Promise<number> |
es | async HandleEvents( | errmsg) |
If your program includes significant loops, you may want to include a call to this function to make sure that the library takes care of the information pushed by the modules on the communication channels. This is not strictly necessary, but it may improve the reactivity of the library for the following commands.
This function may signal an error in case there is a communication problem while contacting a module.
Parameters :
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Initializes the Yoctopuce programming library explicitly.
js | function yInitAPI( | mode, errmsg) |
cpp | YRETCODE InitAPI( | int mode, string errmsg) |
m | +(YRETCODE) InitAPI | :(int) mode :(NSError**) errmsg |
pas | integer yInitAPI( | mode: integer, var errmsg: string): integer |
vb | function InitAPI( | ByVal mode As Integer, ByRef errmsg As String) As Integer |
cs | static int InitAPI( | int mode, ref string errmsg) |
java | int InitAPI( | int mode) |
uwp | async Task<int> InitAPI( | int mode) |
py | InitAPI( | mode, errmsg=None) |
php | function InitAPI( | $mode, &$errmsg) |
ts | async InitAPI( | mode: number, errmsg: YErrorMsg): Promise<number> |
es | async InitAPI( | mode, errmsg) |
It is not strictly needed to call yInitAPI(), as the library is automatically initialized when calling yRegisterHub() for the first time.
When YAPI.DETECT_NONE is used as detection mode, you must explicitly use yRegisterHub() to point the API to the VirtualHub on which your devices are connected before trying to access them.
Parameters :
mode | an integer corresponding to the type of automatic device detection to use. Possible values are YAPI.DETECT_NONE, YAPI.DETECT_USB, YAPI.DETECT_NET, and YAPI.DETECT_ALL. |
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Fault-tolerant alternative to yRegisterHub().
js | function yPreregisterHub( | url, errmsg) |
cpp | YRETCODE PreregisterHub( | string url, string errmsg) |
m | +(YRETCODE) PreregisterHub | :(NSString *) url :(NSError**) errmsg |
pas | integer yPreregisterHub( | url: string, var errmsg: string): integer |
vb | function PreregisterHub( | ByVal url As String, |
ByRef errmsg As String) As Integer |
cs | static int PreregisterHub( | string url, ref string errmsg) |
java | int PreregisterHub( | String url) |
uwp | async Task<int> PreregisterHub( | string url) |
py | PreregisterHub( | url, errmsg=None) |
php | function PreregisterHub( | $url, &$errmsg) |
ts | async PreregisterHub( | url: string, errmsg: YErrorMsg): Promise<number> |
es | async PreregisterHub( | url, errmsg) |
dnp | static string PreregisterHub( | string url) |
cp | static string PreregisterHub( | string url) |
This function has the same purpose and same arguments as yRegisterHub(), but does not trigger an error when the selected hub is not available at the time of the function call. This makes it possible to register a network hub independently of the current connectivity, and to try to contact it only when a device is actively needed.
Parameters :
url | a string containing either "usb","callback" or the root URL of the hub to monitor |
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Register a callback function, to be called each time a device is plugged.
js | function yRegisterDeviceArrivalCallback( | arrivalCallback) |
cpp | void RegisterDeviceArrivalCallback( | yDeviceUpdateCallback arrivalCallback) |
m | +(void) RegisterDeviceArrivalCallback | :(yDeviceUpdateCallback) arrivalCallback |
pas | yRegisterDeviceArrivalCallback( | arrivalCallback: yDeviceUpdateFunc) |
vb | procedure RegisterDeviceArrivalCallback( | ByVal arrivalCallback As yDeviceUpdateFunc) |
cs | static void RegisterDeviceArrivalCallback( | yDeviceUpdateFunc arrivalCallback) |
java | void RegisterDeviceArrivalCallback( | DeviceArrivalCallback arrivalCallback) |
uwp | void RegisterDeviceArrivalCallback( | DeviceUpdateHandler arrivalCallback) |
py | RegisterDeviceArrivalCallback( | arrivalCallback) |
php | function RegisterDeviceArrivalCallback( | $arrivalCallback) |
ts | async RegisterDeviceArrivalCallback( | arrivalCallback: YDeviceUpdateCallback| null): Promise<void> |
es | async RegisterDeviceArrivalCallback( | arrivalCallback) |
This callback will be invoked while yUpdateDeviceList is running. You will have to call this function on a regular basis.
Parameters :
arrivalCallback | a procedure taking a YModule parameter, or null |
Register a callback function, to be called each time a device is unplugged.
js | function yRegisterDeviceRemovalCallback( | removalCallback) |
cpp | void RegisterDeviceRemovalCallback( | yDeviceUpdateCallback removalCallback) |
m | +(void) RegisterDeviceRemovalCallback | :(yDeviceUpdateCallback) removalCallback |
pas | yRegisterDeviceRemovalCallback( | removalCallback: yDeviceUpdateFunc) |
vb | procedure RegisterDeviceRemovalCallback( | ByVal removalCallback As yDeviceUpdateFunc) |
cs | static void RegisterDeviceRemovalCallback( | yDeviceUpdateFunc removalCallback) |
java | void RegisterDeviceRemovalCallback( | DeviceRemovalCallback removalCallback) |
uwp | void RegisterDeviceRemovalCallback( | DeviceUpdateHandler removalCallback) |
py | RegisterDeviceRemovalCallback( | removalCallback) |
php | function RegisterDeviceRemovalCallback( | $removalCallback) |
ts | async RegisterDeviceRemovalCallback( | removalCallback: YDeviceUpdateCallback| null): Promise<void> |
es | async RegisterDeviceRemovalCallback( | removalCallback) |
This callback will be invoked while yUpdateDeviceList is running. You will have to call this function on a regular basis.
Parameters :
removalCallback | a procedure taking a YModule parameter, or null |
Setup the Yoctopuce library to use modules connected on a given machine.
js | function yRegisterHub( | url, errmsg) |
cpp | YRETCODE RegisterHub( | string url, string errmsg) |
m | +(YRETCODE) RegisterHub | :(NSString *) url :(NSError**) errmsg |
pas | integer yRegisterHub( | url: string, var errmsg: string): integer |
vb | function RegisterHub( | ByVal url As String, |
ByRef errmsg As String) As Integer |
cs | static int RegisterHub( | string url, ref string errmsg) |
java | int RegisterHub( | String url) |
uwp | async Task<int> RegisterHub( | string url) |
py | RegisterHub( | url, errmsg=None) |
php | function RegisterHub( | $url, &$errmsg) |
ts | async RegisterHub( | url: string, errmsg: YErrorMsg): Promise<number> |
es | async RegisterHub( | url, errmsg) |
dnp | static string RegisterHub( | string url) |
cp | static string RegisterHub( | string url) |
The parameter will determine how the API will work. Use the following values:
usb: When the usb keyword is used, the API will work with devices connected directly to the USB bus. Some programming languages such a JavaScript, PHP, and Java don't provide direct access to USB hardware, so usb will not work with these. In this case, use a VirtualHub or a networked YoctoHub (see below).
x.x.x.x or hostname: The API will use the devices connected to the host with the given IP address or hostname. That host can be a regular computer running a VirtualHub, or a networked YoctoHub such as YoctoHub-Ethernet or YoctoHub-Wireless. If you want to use the VirtualHub running on you local computer, use the IP address 127.0.0.1.
callback: that keyword make the API run in "HTTP Callback" mode. This a special mode allowing to take control of Yoctopuce devices through a NAT filter when using a VirtualHub or a networked YoctoHub. You only need to configure your hub to call your server script on a regular basis. This mode is currently available for PHP and Node.JS only.
Be aware that only one application can use direct USB access at a given time on a machine. Multiple access would cause conflicts while trying to access the USB modules. In particular, this means that you must stop the VirtualHub software before starting an application that uses direct USB access. The workaround for this limitation is to setup the library to use the VirtualHub rather than direct USB access.
If access control has been activated on the hub, virtual or not, you want to reach, the URL parameter should look like:
http://username:password@address:port
You can call RegisterHub several times to connect to several machines.
Parameters :
url | a string containing either "usb","callback" or the root URL of the hub to monitor |
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Register a callback function, to be called each time an Network Hub send an SSDP message.
cpp | void RegisterHubDiscoveryCallback( | YHubDiscoveryCallback hubDiscoveryCallback) |
m | +(void) RegisterHubDiscoveryCallback | : (YHubDiscoveryCallback) hubDiscoveryCallback |
pas | yRegisterHubDiscoveryCallback( | hubDiscoveryCallback: YHubDiscoveryCallback) |
vb | procedure RegisterHubDiscoveryCallback( | ByVal hubDiscoveryCallback As YHubDiscoveryCallback) |
cs | static void RegisterHubDiscoveryCallback( | YHubDiscoveryCallback hubDiscoveryCallback) |
java | void RegisterHubDiscoveryCallback( | HubDiscoveryCallback hubDiscoveryCallback) |
uwp | async Task RegisterHubDiscoveryCallback( | HubDiscoveryHandler hubDiscoveryCallback) |
py | RegisterHubDiscoveryCallback( | hubDiscoveryCallback) |
ts | async RegisterHubDiscoveryCallback( | hubDiscoveryCallback: YHubDiscoveryCallback): Promise<number> |
es | async RegisterHubDiscoveryCallback( | hubDiscoveryCallback) |
The callback has two string parameter, the first one contain the serial number of the hub and the second contain the URL of the network hub (this URL can be passed to RegisterHub). This callback will be invoked while yUpdateDeviceList is running. You will have to call this function on a regular basis.
Parameters :
hubDiscoveryCallback | a procedure taking two string parameter, the serial |
Variant to yRegisterHub() used to initialize Yoctopuce API on an existing Websocket session, as happens for incoming WebSocket callbacks.
Parameters :
ws | node WebSocket object for the incoming WebSocket callback connection |
errmsg | a string passed by reference to receive any error message. |
authpwd | the optional authentication password, required only authentication is configured on the calling hub. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Registers a log callback function.
cpp | void RegisterLogFunction( | yLogFunction logfun) |
m | +(void) RegisterLogFunction | :(yLogCallback) logfun |
pas | yRegisterLogFunction( | logfun: yLogFunc) |
vb | procedure RegisterLogFunction( | ByVal logfun As yLogFunc) |
cs | static void RegisterLogFunction( | yLogFunc logfun) |
java | void RegisterLogFunction( | LogCallback logfun) |
uwp | void RegisterLogFunction( | LogHandler logfun) |
py | RegisterLogFunction( | logfun) |
ts | async RegisterLogFunction( | logfun: YLogCallback): Promise<number> |
es | async RegisterLogFunction( | logfun) |
This callback will be called each time the API have something to say. Quite useful to debug the API.
Parameters :
logfun | a procedure taking a string parameter, or null |
Select the architecture or the library to be loaded to access to USB.
py | SelectArchitecture( | arch) |
By default, the Python library automatically detects the appropriate library to use. However, for Linux ARM, it not possible to reliably distinguish between a Hard Float (armhf) and a Soft Float (armel) install. For in this case, it is therefore recommended to manually select the proper architecture by calling SelectArchitecture() before any other call to the library.
Parameters :
arch | A string containing the architecture to use. Possibles value are: "armhf","armel", "aarch64","i386","x86_64", "32bit", "64bit" |
Returns :
nothing.
On failure, throws an exception.
Change the validity period of the data loaded by the library.
cpp | static void SetCacheValidity( | u64 cacheValidityMs) |
m | +(void) SetCacheValidity | : (u64) cacheValidityMs |
pas | ySetCacheValidity( | cacheValidityMs: u64) |
vb | procedure SetCacheValidity( | ByVal cacheValidityMs As Long) |
cs | void SetCacheValidity( | ulong cacheValidityMs) |
java | void SetCacheValidity( | long cacheValidityMs) |
uwp | async Task SetCacheValidity( | ulong cacheValidityMs) |
py | SetCacheValidity( | cacheValidityMs) |
php | function SetCacheValidity( | $cacheValidityMs) |
ts | async SetCacheValidity( | cacheValidityMs: number): Promise<void> |
es | async SetCacheValidity( | cacheValidityMs) |
By default, when accessing a module, all the attributes of the module functions are automatically kept in cache for the standard duration (5 ms). This method can be used to change this standard duration, for example in order to reduce network or USB traffic. This parameter does not affect value change callbacks Note: This function must be called after yInitAPI.
Parameters :
cacheValidityMs | an integer corresponding to the validity attributed to the loaded function parameters, in milliseconds. |
(Objective-C only) Register an object that must follow the protocol YDeviceHotPlug.
m | +(void) SetDelegate | :(id) object |
The methods yDeviceArrival and yDeviceRemoval will be invoked while yUpdateDeviceList is running. You will have to call this function on a regular basis.
Parameters :
object | an object that must follow the protocol YAPIDelegate, or nil |
Modifies the delay between each forced enumeration of the used YoctoHubs.
cpp | static void SetDeviceListValidity( | int deviceListValidity) |
m | +(void) SetDeviceListValidity | : (int) deviceListValidity |
pas | ySetDeviceListValidity( | deviceListValidity: LongInt) |
vb | procedure SetDeviceListValidity( | ByVal deviceListValidity As Integer) |
cs | void SetDeviceListValidity( | int deviceListValidity) |
java | void SetDeviceListValidity( | int deviceListValidity) |
uwp | async Task SetDeviceListValidity( | int deviceListValidity) |
py | SetDeviceListValidity( | deviceListValidity) |
php | function SetDeviceListValidity( | $deviceListValidity) |
ts | async SetDeviceListValidity( | deviceListValidity: number): Promise<void> |
es | async SetDeviceListValidity( | deviceListValidity) |
By default, the library performs a full enumeration every 10 seconds. To reduce network traffic, you can increase this delay. It's particularly useful when a YoctoHub is connected to the GSM network where traffic is billed. This parameter doesn't impact modules connected by USB, nor the working of module arrival/removal callbacks. Note: you must call this function after yInitAPI.
Parameters :
deviceListValidity | nubmer of seconds between each enumeration. |
Enables the HTTP callback cache.
php | function SetHTTPCallbackCacheDir( | $str_directory) |
When enabled, this cache reduces the quantity of data sent to the PHP script by 50% to 70%. To enable this cache, the method ySetHTTPCallbackCacheDir() must be called before any call to yRegisterHub(). This method takes in parameter the path of the directory used for saving data between each callback. This folder must exist and the PHP script needs to have write access to it. It is recommended to use a folder that is not published on the Web server since the library will save some data of Yoctopuce devices into this folder.
Note: This feature is supported by YoctoHub and VirtualHub since version 27750.
Parameters :
str_directory | the path of the folder that will be used as cache. |
Returns :
nothing.
On failure, throws an exception.
Modifies the network connection delay for yRegisterHub() and yUpdateDeviceList().
cpp | static void SetNetworkTimeout( | int networkMsTimeout) |
m | +(void) SetNetworkTimeout | : (int) networkMsTimeout |
pas | ySetNetworkTimeout( | networkMsTimeout: LongInt) |
vb | procedure SetNetworkTimeout( | ByVal networkMsTimeout As Integer) |
cs | void SetNetworkTimeout( | int networkMsTimeout) |
java | void SetNetworkTimeout( | int networkMsTimeout) |
uwp | async Task SetNetworkTimeout( | int networkMsTimeout) |
py | SetNetworkTimeout( | networkMsTimeout) |
php | function SetNetworkTimeout( | $networkMsTimeout) |
ts | async SetNetworkTimeout( | networkMsTimeout: number): Promise<void> |
es | async SetNetworkTimeout( | networkMsTimeout) |
dnp | static void SetNetworkTimeout( | int networkMsTimeout) |
cp | static void SetNetworkTimeout( | int networkMsTimeout) |
This delay impacts only the YoctoHubs and VirtualHub which are accessible through the network. By default, this delay is of 20000 milliseconds, but depending or you network you may want to change this delay, gor example if your network infrastructure is based on a GSM connection.
Parameters :
networkMsTimeout | the network connection delay in milliseconds. |
Invoke the specified callback function after a given timeout.
js | function ySetTimeout( | callback, ms_timeout, args) |
ts | SetTimeout( | callback: Function, ms_timeout: number): number |
es | SetTimeout( | callback, ms_timeout, args) |
This function behaves more or less like Javascript setTimeout, but during the waiting time, it will call yHandleEvents and yUpdateDeviceList periodically, in order to keep the API up-to-date with current devices.
Parameters :
callback | the function to call after the timeout occurs. On Microsoft Internet Explorer, the callback must be provided as a string to be evaluated. |
ms_timeout | an integer corresponding to the duration of the timeout, in milliseconds. |
args | additional arguments to be passed to the callback function can be provided, if needed (not supported on Microsoft Internet Explorer). |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Enables the acknowledge of every USB packet received by the Yoctopuce library.
java | void SetUSBPacketAckMs( | int pktAckDelay) |
This function allows the library to run on Android phones that tend to loose USB packets. By default, this feature is disabled because it doubles the number of packets sent and slows down the API considerably. Therefore, the acknowledge of incoming USB packets should only be enabled on phones or tablets that loose USB packets. A delay of 50 milliseconds is generally enough. In case of doubt, contact Yoctopuce support. To disable USB packets acknowledge, call this function with the value 0. Note: this feature is only available on Android.
Parameters :
pktAckDelay | then number of milliseconds before the module |
Pauses the execution flow for a specified duration.
js | function ySleep( | ms_duration, errmsg) |
cpp | YRETCODE Sleep( | unsigned ms_duration, string errmsg) |
m | +(YRETCODE) Sleep | :(unsigned) ms_duration :(NSError **) errmsg |
pas | integer ySleep( | ms_duration: integer, var errmsg: string): integer |
vb | function Sleep( | ByVal ms_duration As Integer, |
ByRef errmsg As String) As Integer |
cs | static int Sleep( | int ms_duration, ref string errmsg) |
java | int Sleep( | long ms_duration) |
uwp | async Task<int> Sleep( | ulong ms_duration) |
py | Sleep( | ms_duration, errmsg=None) |
php | function Sleep( | $ms_duration, &$errmsg) |
ts | async Sleep( | ms_duration: number, errmsg: YErrorMsg | null): Promise<number> |
es | async Sleep( | ms_duration, errmsg) |
This function implements a passive waiting loop, meaning that it does not consume CPU cycles significantly. The processor is left available for other threads and processes. During the pause, the library nevertheless reads from time to time information from the Yoctopuce modules by calling yHandleEvents(), in order to stay up-to-date.
This function may signal an error in case there is a communication problem while contacting a module.
Parameters :
ms_duration | an integer corresponding to the duration of the pause, in milliseconds. |
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Test if the hub is reachable.
cpp | YRETCODE TestHub( | string url, int mstimeout, string errmsg) |
m | +(YRETCODE) TestHub | : (NSString*) url |
: (int) mstimeout | ||
: (NSError**) errmsg |
pas | integer yTestHub( | url: string, |
mstimeout: integer, | ||
var errmsg: string): integer |
vb | function TestHub( | ByVal url As String, |
ByVal mstimeout As Integer, | ||
ByRef errmsg As String) As Integer |
cs | static int TestHub( | string url, int mstimeout, ref string errmsg) |
java | int TestHub( | String url, int mstimeout) |
uwp | async Task<int> TestHub( | string url, uint mstimeout) |
py | TestHub( | url, mstimeout, errmsg=None) |
php | function TestHub( | $url, $mstimeout, &$errmsg) |
ts | async TestHub( | url: string, mstimeout: number, errmsg: YErrorMsg): Promise<number> |
es | async TestHub( | url, mstimeout, errmsg) |
dnp | static string TestHub( | string url, int mstimeout) |
cp | static string TestHub( | string url, int mstimeout) |
This method do not register the hub, it only test if the hub is usable. The url parameter follow the same convention as the yRegisterHub method. This method is useful to verify the authentication parameters for a hub. It is possible to force this method to return after mstimeout milliseconds.
Parameters :
url | a string containing either "usb","callback" or the root URL of the hub to monitor |
mstimeout | the number of millisecond available to test the connection. |
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure returns a negative error code.
Force a hub discovery, if a callback as been registered with yRegisterHubDiscoveryCallback it will be called for each net work hub that will respond to the discovery.
cpp | YRETCODE TriggerHubDiscovery( | string errmsg) |
m | +(YRETCODE) TriggerHubDiscovery | : (NSError**) errmsg |
pas | integer yTriggerHubDiscovery( | var errmsg: string): integer |
vb | function TriggerHubDiscovery( | ByRef errmsg As String) As Integer |
cs | static int TriggerHubDiscovery( | ref string errmsg) |
java | int TriggerHubDiscovery( | ) |
uwp | Task<int> TriggerHubDiscovery( | ) |
py | TriggerHubDiscovery( | errmsg=None) |
ts | async TriggerHubDiscovery( | errmsg: YErrorMsg | null): Promise<number> |
es | async TriggerHubDiscovery( | errmsg) |
Parameters :
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds. On failure, throws an exception or returns a negative error code.
Setup the Yoctopuce library to no more use modules connected on a previously registered machine with RegisterHub.
js | function yUnregisterHub( | url) |
cpp | void UnregisterHub( | string url) |
m | +(void) UnregisterHub | :(NSString *) url |
pas | yUnregisterHub( | url: string) |
vb | procedure UnregisterHub( | ByVal url As String) |
cs | static void UnregisterHub( | string url) |
java | void UnregisterHub( | String url) |
uwp | async Task UnregisterHub( | string url) |
py | UnregisterHub( | url) |
php | function UnregisterHub( | $url) |
ts | async UnregisterHub( | url: string): Promise<void> |
es | async UnregisterHub( | url) |
Parameters :
url | a string containing either "usb" or the |
Triggers a (re)detection of connected Yoctopuce modules.
js | function yUpdateDeviceList( | errmsg) |
cpp | YRETCODE UpdateDeviceList( | string errmsg) |
m | +(YRETCODE) UpdateDeviceList | :(NSError**) errmsg |
pas | integer yUpdateDeviceList( | var errmsg: string): integer |
vb | function UpdateDeviceList( | ByRef errmsg As String) As YRETCODE |
cs | static YRETCODE UpdateDeviceList( | ref string errmsg) |
java | int UpdateDeviceList( | ) |
uwp | async Task<int> UpdateDeviceList( | ) |
py | UpdateDeviceList( | errmsg=None) |
php | function UpdateDeviceList( | &$errmsg) |
ts | async UpdateDeviceList( | errmsg: YErrorMsg | null): Promise<number> |
es | async UpdateDeviceList( | errmsg) |
The library searches the machines or USB ports previously registered using yRegisterHub(), and invokes any user-defined callback function in case a change in the list of connected devices is detected.
This function can be called as frequently as desired to refresh the device list and to make the application aware of hot-plug events. However, since device detection is quite a heavy process, UpdateDeviceList shouldn't be called more than once every two seconds.
Parameters :
errmsg | a string passed by reference to receive any error message. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Triggers a (re)detection of connected Yoctopuce modules.
js | function yUpdateDeviceList_async( | callback, context) |
The library searches the machines or USB ports previously registered using yRegisterHub(), and invokes any user-defined callback function in case a change in the list of connected devices is detected.
This function can be called as frequently as desired to refresh the device list and to make the application aware of hot-plug events.
This asynchronous version exists only in JavaScript. It uses a callback instead of a return value in order to avoid blocking Firefox JavaScript VM that does not implement context switching during blocking I/O calls.
Parameters :
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the result code (YAPI.SUCCESS if the operation completes successfully) and the error message. |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Global parameters control interface for all Yoctopuce devices
The YModule class can be used with all Yoctopuce USB devices. It can be used to control the module global parameters, and to enumerate the functions provided by each module.
In order to use the functions described here, you should include:
js | <script type='text/javascript' src='yocto_api.js'></script> |
cpp | #include "yocto_api.h" |
m | #import "yocto_api.h" |
pas | uses yocto_api; |
vb | yocto_api.vb |
cs | yocto_api.cs |
java | import com.yoctopuce.YoctoAPI.YModule; |
uwp | import com.yoctopuce.YoctoAPI.YModule; |
py | from yocto_api import * |
php | require_once('yocto_api.php'); |
ts | in HTML: import { YAPI, YErrorMsg, YModule, YSensor } from '../../dist/esm/yocto_api_browser.js'; in Node.js: import { YAPI, YErrorMsg, YModule, YSensor } from 'yoctolib-cjs/yocto_api_nodejs.js'; |
es | in HTML: <script src="../../lib/yocto_api.js"></script> in node.js: require('yoctolib-es2017/yocto_api.js'); |
dnp | import YoctoProxyAPI.YModuleProxy |
cp | #include "yocto_module_proxy.h" |
vi | YModule.vi |
ml | import YoctoProxyAPI.YModuleProxy" |
Global functions |
---|
YModule.FindModule(func) |
Allows you to find a module from its serial number or from its logical name. |
YModule.FindModuleInContext(yctx, func) |
Retrieves a module for a given identifier in a YAPI context. |
YModule.FirstModule() |
Starts the enumeration of modules currently accessible. |
YModule properties |
module→Beacon [writable] |
State of the localization beacon. |
module→FirmwareRelease [read-only] |
Version of the firmware embedded in the module. |
module→FunctionId [read-only] |
Retrieves the hardware identifier of the nth function on the module. |
module→HardwareId [read-only] |
Unique hardware identifier of the module. |
module→IsOnline [read-only] |
Checks if the module is currently reachable. |
module→LogicalName [writable] |
Logical name of the module. |
module→Luminosity [writable] |
Luminosity of the module informative LEDs (from 0 to 100). |
module→ProductId [read-only] |
USB device identifier of the module. |
module→ProductName [read-only] |
Commercial name of the module, as set by the factory. |
module→ProductRelease [read-only] |
Release number of the module hardware, preprogrammed at the factory. |
module→SerialNumber [read-only] |
Serial number of the module, as set by the factory. |
YModule methods |
module→checkFirmware(path, onlynew) |
Tests whether the byn file is valid for this module. |
module→clearCache() |
Invalidates the cache. |
module→describe() |
Returns a descriptive text that identifies the module. |
module→download(pathname) |
Downloads the specified built-in file and returns a binary buffer with its content. |
module→functionBaseType(functionIndex) |
Retrieves the base type of the nth function on the module. |
module→functionCount() |
Returns the number of functions (beside the "module" interface) available on the module. |
module→functionId(functionIndex) |
Retrieves the hardware identifier of the nth function on the module. |
module→functionName(functionIndex) |
Retrieves the logical name of the nth function on the module. |
module→functionType(functionIndex) |
Retrieves the type of the nth function on the module. |
module→functionValue(functionIndex) |
Retrieves the advertised value of the nth function on the module. |
module→get_allSettings() |
Returns all the settings and uploaded files of the module. |
module→get_beacon() |
Returns the state of the localization beacon. |
module→get_errorMessage() |
Returns the error message of the latest error with this module object. |
module→get_errorType() |
Returns the numerical error code of the latest error with this module object. |
module→get_firmwareRelease() |
Returns the version of the firmware embedded in the module. |
module→get_functionIds(funType) |
Retrieve all hardware identifier that match the type passed in argument. |
module→get_hardwareId() |
Returns the unique hardware identifier of the module. |
module→get_icon2d() |
Returns the icon of the module. |
module→get_lastLogs() |
Returns a string with last logs of the module. |
module→get_logicalName() |
Returns the logical name of the module. |
module→get_luminosity() |
Returns the luminosity of the module informative LEDs (from 0 to 100). |
module→get_parentHub() |
Returns the serial number of the YoctoHub on which this module is connected. |
module→get_persistentSettings() |
Returns the current state of persistent module settings. |
module→get_productId() |
Returns the USB device identifier of the module. |
module→get_productName() |
Returns the commercial name of the module, as set by the factory. |
module→get_productRelease() |
Returns the release number of the module hardware, preprogrammed at the factory. |
module→get_rebootCountdown() |
Returns the remaining number of seconds before the module restarts, or zero when no reboot has been scheduled. |
module→get_serialNumber() |
Returns the serial number of the module, as set by the factory. |
module→get_subDevices() |
Returns a list of all the modules that are plugged into the current module. |
module→get_upTime() |
Returns the number of milliseconds spent since the module was powered on. |
module→get_url() |
Returns the URL used to access the module. |
module→get_usbCurrent() |
Returns the current consumed by the module on the USB bus, in milli-amps. |
module→get_userData() |
Returns the value of the userData attribute, as previously stored using method set_userData. |
module→get_userVar() |
Returns the value previously stored in this attribute. |
module→hasFunction(funcId) |
Tests if the device includes a specific function. |
module→isOnline() |
Checks if the module is currently reachable, without raising any error. |
module→isOnline_async(callback, context) |
Checks if the module is currently reachable, without raising any error. |
module→load(msValidity) |
Preloads the module cache with a specified validity duration. |
module→load_async(msValidity, callback, context) |
Preloads the module cache with a specified validity duration (asynchronous version). |
module→log(text) |
Adds a text message to the device logs. |
module→nextModule() |
Continues the module enumeration started using yFirstModule(). |
module→reboot(secBeforeReboot) |
Schedules a simple module reboot after the given number of seconds. |
module→registerBeaconCallback(callback) |
Register a callback function, to be called when the localization beacon of the module has been changed. |
module→registerConfigChangeCallback(callback) |
Register a callback function, to be called when a persistent settings in a device configuration has been changed (e.g. |
module→registerLogCallback(callback) |
Registers a device log callback function. |
module→revertFromFlash() |
Reloads the settings stored in the nonvolatile memory, as when the module is powered on. |
module→saveToFlash() |
Saves current settings in the nonvolatile memory of the module. |
module→set_allSettings(settings) |
Restores all the settings of the device. |
module→set_allSettingsAndFiles(settings) |
Restores all the settings and uploaded files to the module. |
module→set_beacon(newval) |
Turns on or off the module localization beacon. |
module→set_logicalName(newval) |
Changes the logical name of the module. |
module→set_luminosity(newval) |
Changes the luminosity of the module informative leds. |
module→set_userData(data) |
Stores a user context provided as argument in the userData attribute of the function. |
module→set_userVar(newval) |
Stores a 32 bit value in the device RAM. |
module→triggerConfigChangeCallback() |
Triggers a configuration change callback, to check if they are supported or not. |
module→triggerFirmwareUpdate(secBeforeReboot) |
Schedules a module reboot into special firmware update mode. |
module→updateFirmware(path) |
Prepares a firmware update of the module. |
module→updateFirmwareEx(path, force) |
Prepares a firmware update of the module. |
module→wait_async(callback, context) |
Waits for all pending asynchronous commands on the module to complete, and invoke the user-provided callback function. |
Allows you to find a module from its serial number or from its logical name.
js | function yFindModule( | func) |
cpp | YModule* FindModule( | string func) |
m | +(YModule*) FindModule | : (NSString*) func |
pas | TYModule yFindModule( | func: string): TYModule |
vb | function FindModule( | ByVal func As String) As YModule |
cs | static YModule FindModule( | string func) |
java | static YModule FindModule( | String func) |
uwp | static YModule FindModule( | string func) |
py | FindModule( | func) |
php | function FindModule( | $func) |
ts | static FindModule( | func: string): YModule |
es | static FindModule( | func) |
dnp | static YModuleProxy FindModule( | string func) |
cp | static YModuleProxy * FindModule( | string func) |
This function does not require that the module is online at the time it is invoked. The returned object is nevertheless valid. Use the method YModule.isOnline() to test if the module is indeed online at a given time. In case of ambiguity when looking for a module by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.
If a call to this object's is_online() method returns FALSE although you are certain that the device is plugged, make sure that you did call registerHub() at application initialization time.
Parameters :
func | a string containing either the serial number or the logical name of the desired module |
Returns :
a YModule object allowing you to drive the module or get additional information on the module.
Retrieves a module for a given identifier in a YAPI context.
java | static YModule FindModuleInContext( | YAPIContext yctx, String func) |
uwp | static YModule FindModuleInContext( | YAPIContext yctx, string func) |
ts | static FindModuleInContext( | yctx: YAPIContext, func: string): YModule |
es | static FindModuleInContext( | yctx, func) |
The identifier can be specified using several formats:
This function does not require that the module is online at the time it is invoked. The returned object is nevertheless valid. Use the method YModule.isOnline() to test if the module is indeed online at a given time. In case of ambiguity when looking for a module by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.
Parameters :
yctx | a YAPI context |
func | a string that uniquely characterizes the module, for instance MyDevice.module. |
Returns :
a YModule object allowing you to drive the module.
Starts the enumeration of modules currently accessible.
js | function yFirstModule( | ) |
cpp | YModule * FirstModule( | ) |
m | +(YModule*) FirstModule |
pas | TYModule yFirstModule( | ): TYModule |
vb | function FirstModule( | ) As YModule |
cs | static YModule FirstModule( | ) |
java | static YModule FirstModule( | ) |
uwp | static YModule FirstModule( | ) |
py | FirstModule( | ) |
php | function FirstModule( | ) |
ts | static FirstModule( | ): YModule | null |
es | static FirstModule( | ) |
Use the method YModule.nextModule() to iterate on the next modules.
Returns :
a pointer to a YModule object, corresponding to the first module currently online, or a null pointer if there are none.
State of the localization beacon.
dnp | int Beacon |
Writable. Turns on or off the module localization beacon.
Version of the firmware embedded in the module.
dnp | string FirmwareRelease |
Retrieves the hardware identifier of the nth function on the module.
dnp | string FunctionId |
@param functionIndex : the index of the function for which the information is desired, starting at 0 for the first function.
Unique hardware identifier of the module.
dnp | string HardwareId |
The unique hardware identifier is made of the device serial number followed by string ".module".
Checks if the module is currently reachable.
dnp | bool IsOnline |
If there are valid cached values for the module, that have not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the requested module.
Logical name of the module.
dnp | string LogicalName |
Writable. You can use yCheckLogicalName() prior to this call to make sure that your parameter is valid. Remember to call the saveToFlash() method of the module if the modification must be kept.
Luminosity of the module informative LEDs (from 0 to 100).
dnp | int Luminosity |
Writable. Changes the luminosity of the module informative leds. The parameter is a value between 0 and 100. Remember to call the saveToFlash() method of the module if the modification must be kept.
USB device identifier of the module.
dnp | int ProductId |
Commercial name of the module, as set by the factory.
dnp | string ProductName |
Release number of the module hardware, preprogrammed at the factory.
dnp | int ProductRelease |
The original hardware release returns value 1, revision B returns value 2, etc.
Serial number of the module, as set by the factory.
dnp | string SerialNumber |
Tests whether the byn file is valid for this module.
js | function checkFirmware( | path, onlynew) |
cpp | string checkFirmware( | string path, bool onlynew) |
m | -(NSString*) checkFirmware | : (NSString*) path |
: (bool) onlynew |
pas | string checkFirmware( | path: string, onlynew: boolean): string |
vb | function checkFirmware( | ByVal path As String, ByVal onlynew As Boolean) As String |
cs | string checkFirmware( | string path, bool onlynew) |
java | String checkFirmware( | String path, boolean onlynew) |
uwp | async Task<string> checkFirmware( | string path, bool onlynew) |
py | checkFirmware( | path, onlynew) |
php | function checkFirmware( | $path, $onlynew) |
ts | async checkFirmware( | path: string, onlynew: boolean): Promise<string> |
es | async checkFirmware( | path, onlynew) |
dnp | string checkFirmware( | string path, bool onlynew) |
cp | string checkFirmware( | string path, bool onlynew) |
cmd | YModule target checkFirmware | path onlynew |
This method is useful to test if the module needs to be updated. It is possible to pass a directory as argument instead of a file. In this case, this method returns the path of the most recent appropriate .byn file. If the parameter onlynew is true, the function discards firmwares that are older or equal to the installed firmware.
Parameters :
path | the path of a byn file or a directory that contains byn files |
onlynew | returns only files that are strictly newer |
Returns :
the path of the byn file to use or a empty string if no byn files matches the requirement
On failure, throws an exception or returns a string that start with "error:".
Invalidates the cache.
js | function clearCache( | ) |
cpp | void clearCache( | ) |
m | -(void) clearCache |
pas | clearCache( | ) |
vb | procedure clearCache( | ) |
cs | void clearCache( | ) |
java | void clearCache( | ) |
py | clearCache( | ) |
php | function clearCache( | ) |
ts | async clearCache( | ): Promise<void> |
es | async clearCache( | ) |
Invalidates the cache of the module attributes. Forces the next call to get_xxx() or loadxxx() to use values that come from the device.
Returns a descriptive text that identifies the module.
js | function describe( | ) |
cpp | string describe( | ) |
m | -(NSString*) describe |
pas | string describe( | ): string |
vb | function describe( | ) As String |
cs | string describe( | ) |
java | String describe( | ) |
py | describe( | ) |
php | function describe( | ) |
ts | async describe( | ): Promise<string> |
es | async describe( | ) |
The text may include either the logical name or the serial number of the module.
Returns :
a string that describes the module
Downloads the specified built-in file and returns a binary buffer with its content.
js | function download( | pathname) |
cpp | string download( | string pathname) |
m | -(NSMutableData*) download | : (NSString*) pathname |
pas | TByteArray download( | pathname: string): TByteArray |
vb | function download( | ByVal pathname As String) As Byte |
cs | byte[] download( | string pathname) |
java | byte[] download( | String pathname) |
uwp | async Task<byte[]> download( | string pathname) |
py | download( | pathname) |
php | function download( | $pathname) |
ts | async download( | pathname: string): Promise<Uint8Array> |
es | async download( | pathname) |
dnp | byte[] download( | string pathname) |
cp | string download( | string pathname) |
cmd | YModule target download | pathname |
Parameters :
pathname | name of the new file to load |
Returns :
a binary buffer with the file content
On failure, throws an exception or returns YAPI_INVALID_STRING.
Retrieves the base type of the nth function on the module.
js | function functionBaseType( | functionIndex) |
cpp | string functionBaseType( | int functionIndex) |
pas | string functionBaseType( | functionIndex: integer): string |
vb | function functionBaseType( | ByVal functionIndex As Integer) As String |
cs | string functionBaseType( | int functionIndex) |
java | String functionBaseType( | int functionIndex) |
py | functionBaseType( | functionIndex) |
php | function functionBaseType( | $functionIndex) |
ts | async functionBaseType( | functionIndex: number): Promise<string> |
es | async functionBaseType( | functionIndex) |
For instance, the base type of all measuring functions is "Sensor".
Parameters :
functionIndex | the index of the function for which the information is desired, starting at 0 for the first function. |
Returns :
a string corresponding to the base type of the function
On failure, throws an exception or returns an empty string.
Returns the number of functions (beside the "module" interface) available on the module.
js | function functionCount( | ) |
cpp | int functionCount( | ) |
m | -(int) functionCount |
pas | integer functionCount( | ): integer |
vb | function functionCount( | ) As Integer |
cs | int functionCount( | ) |
java | int functionCount( | ) |
py | functionCount( | ) |
php | function functionCount( | ) |
ts | async functionCount( | ): Promise<number> |
es | async functionCount( | ) |
Returns :
the number of functions on the module
On failure, throws an exception or returns a negative error code.
Retrieves the hardware identifier of the nth function on the module.
js | function functionId( | functionIndex) |
cpp | string functionId( | int functionIndex) |
m | -(NSString*) functionId | : (int) functionIndex |
pas | string functionId( | functionIndex: integer): string |
vb | function functionId( | ByVal functionIndex As Integer) As String |
cs | string functionId( | int functionIndex) |
java | String functionId( | int functionIndex) |
py | functionId( | functionIndex) |
php | function functionId( | $functionIndex) |
ts | async functionId( | functionIndex: number): Promise<string> |
es | async functionId( | functionIndex) |
Parameters :
functionIndex | the index of the function for which the information is desired, starting at 0 for the first function. |
Returns :
a string corresponding to the unambiguous hardware identifier of the requested module function
On failure, throws an exception or returns an empty string.
Retrieves the logical name of the nth function on the module.
js | function functionName( | functionIndex) |
cpp | string functionName( | int functionIndex) |
m | -(NSString*) functionName | : (int) functionIndex |
pas | string functionName( | functionIndex: integer): string |
vb | function functionName( | ByVal functionIndex As Integer) As String |
cs | string functionName( | int functionIndex) |
java | String functionName( | int functionIndex) |
py | functionName( | functionIndex) |
php | function functionName( | $functionIndex) |
ts | async functionName( | functionIndex: number): Promise<string> |
es | async functionName( | functionIndex) |
Parameters :
functionIndex | the index of the function for which the information is desired, starting at 0 for the first function. |
Returns :
a string corresponding to the logical name of the requested module function
On failure, throws an exception or returns an empty string.
Retrieves the type of the nth function on the module.
js | function functionType( | functionIndex) |
cpp | string functionType( | int functionIndex) |
pas | string functionType( | functionIndex: integer): string |
vb | function functionType( | ByVal functionIndex As Integer) As String |
cs | string functionType( | int functionIndex) |
java | String functionType( | int functionIndex) |
py | functionType( | functionIndex) |
php | function functionType( | $functionIndex) |
ts | async functionType( | functionIndex: number): Promise<string> |
es | async functionType( | functionIndex) |
Parameters :
functionIndex | the index of the function for which the information is desired, starting at 0 for the first function. |
Returns :
a string corresponding to the type of the function
On failure, throws an exception or returns an empty string.
Retrieves the advertised value of the nth function on the module.
js | function functionValue( | functionIndex) |
cpp | string functionValue( | int functionIndex) |
m | -(NSString*) functionValue | : (int) functionIndex |
pas | string functionValue( | functionIndex: integer): string |
vb | function functionValue( | ByVal functionIndex As Integer) As String |
cs | string functionValue( | int functionIndex) |
java | String functionValue( | int functionIndex) |
py | functionValue( | functionIndex) |
php | function functionValue( | $functionIndex) |
ts | async functionValue( | functionIndex: number): Promise<string> |
es | async functionValue( | functionIndex) |
Parameters :
functionIndex | the index of the function for which the information is desired, starting at 0 for the first function. |
Returns :
a short string (up to 6 characters) corresponding to the advertised value of the requested module function
On failure, throws an exception or returns an empty string.
Returns all the settings and uploaded files of the module.
js | function get_allSettings( | ) |
cpp | string get_allSettings( | ) |
m | -(NSMutableData*) allSettings |
pas | TByteArray get_allSettings( | ): TByteArray |
vb | function get_allSettings( | ) As Byte |
cs | byte[] get_allSettings( | ) |
java | byte[] get_allSettings( | ) |
uwp | async Task<byte[]> get_allSettings( | ) |
py | get_allSettings( | ) |
php | function get_allSettings( | ) |
ts | async get_allSettings( | ): Promise<Uint8Array> |
es | async get_allSettings( | ) |
dnp | byte[] get_allSettings( | ) |
cp | string get_allSettings( | ) |
cmd | YModule target get_allSettings |
Useful to backup all the logical names, calibrations parameters, and uploaded files of a device.
Returns :
a binary buffer with all the settings.
On failure, throws an exception or returns an binary object of size 0.
Returns the state of the localization beacon.
js | function get_beacon( | ) |
cpp | Y_BEACON_enum get_beacon( | ) |
m | -(Y_BEACON_enum) beacon |
pas | Integer get_beacon( | ): Integer |
vb | function get_beacon( | ) As Integer |
cs | int get_beacon( | ) |
java | int get_beacon( | ) |
uwp | async Task<int> get_beacon( | ) |
py | get_beacon( | ) |
php | function get_beacon( | ) |
ts | async get_beacon( | ): Promise<YModule_Beacon> |
es | async get_beacon( | ) |
dnp | int get_beacon( | ) |
cp | int get_beacon( | ) |
cmd | YModule target get_beacon |
Returns :
either YModule.BEACON_OFF or YModule.BEACON_ON, according to the state of the localization beacon
On failure, throws an exception or returns YModule.BEACON_INVALID.
Returns the error message of the latest error with this module object.
js | function get_errorMessage( | ) |
cpp | string get_errorMessage( | ) |
m | -(NSString*) errorMessage |
pas | string get_errorMessage( | ): string |
vb | function get_errorMessage( | ) As String |
cs | string get_errorMessage( | ) |
java | String get_errorMessage( | ) |
py | get_errorMessage( | ) |
php | function get_errorMessage( | ) |
ts | get_errorMessage( | ): string |
es | get_errorMessage( | ) |
This method is mostly useful when using the Yoctopuce library with exceptions disabled.
Returns :
a string corresponding to the latest error message that occurred while using this module object
Returns the numerical error code of the latest error with this module object.
js | function get_errorType( | ) |
cpp | YRETCODE get_errorType( | ) |
m | -(YRETCODE) errorType |
pas | YRETCODE get_errorType( | ): YRETCODE |
vb | function get_errorType( | ) As YRETCODE |
cs | YRETCODE get_errorType( | ) |
java | int get_errorType( | ) |
py | get_errorType( | ) |
php | function get_errorType( | ) |
ts | get_errorType( | ): number |
es | get_errorType( | ) |
This method is mostly useful when using the Yoctopuce library with exceptions disabled.
Returns :
a number corresponding to the code of the latest error that occurred while using this module object
Returns the version of the firmware embedded in the module.
js | function get_firmwareRelease( | ) |
cpp | string get_firmwareRelease( | ) |
m | -(NSString*) firmwareRelease |
pas | string get_firmwareRelease( | ): string |
vb | function get_firmwareRelease( | ) As String |
cs | string get_firmwareRelease( | ) |
java | String get_firmwareRelease( | ) |
uwp | async Task<string> get_firmwareRelease( | ) |
py | get_firmwareRelease( | ) |
php | function get_firmwareRelease( | ) |
ts | async get_firmwareRelease( | ): Promise<string> |
es | async get_firmwareRelease( | ) |
dnp | string get_firmwareRelease( | ) |
cp | string get_firmwareRelease( | ) |
cmd | YModule target get_firmwareRelease |
Returns :
a string corresponding to the version of the firmware embedded in the module
On failure, throws an exception or returns YModule.FIRMWARERELEASE_INVALID.
Retrieve all hardware identifier that match the type passed in argument.
js | function get_functionIds( | funType) |
cpp | vector<string> get_functionIds( | string funType) |
m | -(NSMutableArray*) functionIds | : (NSString*) funType |
pas | TStringArray get_functionIds( | funType: string): TStringArray |
vb | function get_functionIds( | ByVal funType As String) As List |
cs | List<string> get_functionIds( | string funType) |
java | ArrayList<String> get_functionIds( | String funType) |
uwp | async Task<List<string>> get_functionIds( | string funType) |
py | get_functionIds( | funType) |
php | function get_functionIds( | $funType) |
ts | async get_functionIds( | funType: string): Promise<string[] |
es | async get_functionIds( | funType) |
dnp | string[] get_functionIds( | string funType) |
cp | vector<string> get_functionIds( | string funType) |
cmd | YModule target get_functionIds | funType |
Parameters :
funType | The type of function (Relay, LightSensor, Voltage,...) |
Returns :
an array of strings.
Returns the unique hardware identifier of the module.
js | function get_hardwareId( | ) |
cpp | string get_hardwareId( | ) |
m | -(NSString*) hardwareId |
vb | function get_hardwareId( | ) As String |
cs | string get_hardwareId( | ) |
java | String get_hardwareId( | ) |
py | get_hardwareId( | ) |
php | function get_hardwareId( | ) |
ts | async get_hardwareId( | ): Promise<string> |
es | async get_hardwareId( | ) |
dnp | string get_hardwareId( | ) |
cp | string get_hardwareId( | ) |
pas | string get_hardwareId( | ): string |
uwp | async Task<string> get_hardwareId( | ) |
cmd | YModule target get_hardwareId |
The unique hardware identifier is made of the device serial number followed by string ".module".
Returns :
a string that uniquely identifies the module
Returns the icon of the module.
js | function get_icon2d( | ) |
cpp | string get_icon2d( | ) |
m | -(NSMutableData*) icon2d |
pas | TByteArray get_icon2d( | ): TByteArray |
vb | function get_icon2d( | ) As Byte |
cs | byte[] get_icon2d( | ) |
java | byte[] get_icon2d( | ) |
uwp | async Task<byte[]> get_icon2d( | ) |
py | get_icon2d( | ) |
php | function get_icon2d( | ) |
ts | async get_icon2d( | ): Promise<Uint8Array> |
es | async get_icon2d( | ) |
dnp | byte[] get_icon2d( | ) |
cp | string get_icon2d( | ) |
cmd | YModule target get_icon2d |
The icon is a PNG image and does not exceeds 1536 bytes.
Returns :
a binary buffer with module icon, in png format. On failure, throws an exception or returns YAPI_INVALID_STRING.
Returns a string with last logs of the module.
js | function get_lastLogs( | ) |
cpp | string get_lastLogs( | ) |
m | -(NSString*) lastLogs |
pas | string get_lastLogs( | ): string |
vb | function get_lastLogs( | ) As String |
cs | string get_lastLogs( | ) |
java | String get_lastLogs( | ) |
uwp | async Task<string> get_lastLogs( | ) |
py | get_lastLogs( | ) |
php | function get_lastLogs( | ) |
ts | async get_lastLogs( | ): Promise<string> |
es | async get_lastLogs( | ) |
dnp | string get_lastLogs( | ) |
cp | string get_lastLogs( | ) |
cmd | YModule target get_lastLogs |
This method return only logs that are still in the module.
Returns :
a string with last logs of the module. On failure, throws an exception or returns YAPI_INVALID_STRING.
Returns the logical name of the module.
js | function get_logicalName( | ) |
cpp | string get_logicalName( | ) |
m | -(NSString*) logicalName |
pas | string get_logicalName( | ): string |
vb | function get_logicalName( | ) As String |
cs | string get_logicalName( | ) |
java | String get_logicalName( | ) |
uwp | async Task<string> get_logicalName( | ) |
py | get_logicalName( | ) |
php | function get_logicalName( | ) |
ts | async get_logicalName( | ): Promise<string> |
es | async get_logicalName( | ) |
dnp | string get_logicalName( | ) |
cp | string get_logicalName( | ) |
cmd | YModule target get_logicalName |
Returns :
a string corresponding to the logical name of the module
On failure, throws an exception or returns YModule.LOGICALNAME_INVALID.
Returns the luminosity of the module informative LEDs (from 0 to 100).
js | function get_luminosity( | ) |
cpp | int get_luminosity( | ) |
m | -(int) luminosity |
pas | LongInt get_luminosity( | ): LongInt |
vb | function get_luminosity( | ) As Integer |
cs | int get_luminosity( | ) |
java | int get_luminosity( | ) |
uwp | async Task<int> get_luminosity( | ) |
py | get_luminosity( | ) |
php | function get_luminosity( | ) |
ts | async get_luminosity( | ): Promise<number> |
es | async get_luminosity( | ) |
dnp | int get_luminosity( | ) |
cp | int get_luminosity( | ) |
cmd | YModule target get_luminosity |
Returns :
an integer corresponding to the luminosity of the module informative LEDs (from 0 to 100)
On failure, throws an exception or returns YModule.LUMINOSITY_INVALID.
Returns the serial number of the YoctoHub on which this module is connected.
js | function get_parentHub( | ) |
cpp | string get_parentHub( | ) |
m | -(NSString*) parentHub |
pas | string get_parentHub( | ): string |
vb | function get_parentHub( | ) As String |
cs | string get_parentHub( | ) |
java | String get_parentHub( | ) |
uwp | async Task<string> get_parentHub( | ) |
py | get_parentHub( | ) |
php | function get_parentHub( | ) |
ts | async get_parentHub( | ): Promise<string> |
es | async get_parentHub( | ) |
dnp | string get_parentHub( | ) |
cp | string get_parentHub( | ) |
cmd | YModule target get_parentHub |
If the module is connected by USB, or if the module is the root YoctoHub, an empty string is returned.
Returns :
a string with the serial number of the YoctoHub or an empty string
Returns the current state of persistent module settings.
js | function get_persistentSettings( | ) |
cpp | Y_PERSISTENTSETTINGS_enum get_persistentSettings( | ) |
m | -(Y_PERSISTENTSETTINGS_enum) persistentSettings |
pas | Integer get_persistentSettings( | ): Integer |
vb | function get_persistentSettings( | ) As Integer |
cs | int get_persistentSettings( | ) |
java | int get_persistentSettings( | ) |
uwp | async Task<int> get_persistentSettings( | ) |
py | get_persistentSettings( | ) |
php | function get_persistentSettings( | ) |
ts | async get_persistentSettings( | ): Promise<YModule_PersistentSettings> |
es | async get_persistentSettings( | ) |
dnp | int get_persistentSettings( | ) |
cp | int get_persistentSettings( | ) |
cmd | YModule target get_persistentSettings |
Returns :
a value among YModule.PERSISTENTSETTINGS_LOADED, YModule.PERSISTENTSETTINGS_SAVED and YModule.PERSISTENTSETTINGS_MODIFIED corresponding to the current state of persistent module settings
On failure, throws an exception or returns YModule.PERSISTENTSETTINGS_INVALID.
Returns the USB device identifier of the module.
js | function get_productId( | ) |
cpp | int get_productId( | ) |
m | -(int) productId |
pas | LongInt get_productId( | ): LongInt |
vb | function get_productId( | ) As Integer |
cs | int get_productId( | ) |
java | int get_productId( | ) |
uwp | async Task<int> get_productId( | ) |
py | get_productId( | ) |
php | function get_productId( | ) |
ts | async get_productId( | ): Promise<number> |
es | async get_productId( | ) |
dnp | int get_productId( | ) |
cp | int get_productId( | ) |
cmd | YModule target get_productId |
Returns :
an integer corresponding to the USB device identifier of the module
On failure, throws an exception or returns YModule.PRODUCTID_INVALID.
Returns the commercial name of the module, as set by the factory.
js | function get_productName( | ) |
cpp | string get_productName( | ) |
m | -(NSString*) productName |
pas | string get_productName( | ): string |
vb | function get_productName( | ) As String |
cs | string get_productName( | ) |
java | String get_productName( | ) |
uwp | async Task<string> get_productName( | ) |
py | get_productName( | ) |
php | function get_productName( | ) |
ts | async get_productName( | ): Promise<string> |
es | async get_productName( | ) |
dnp | string get_productName( | ) |
cp | string get_productName( | ) |
cmd | YModule target get_productName |
Returns :
a string corresponding to the commercial name of the module, as set by the factory
On failure, throws an exception or returns YModule.PRODUCTNAME_INVALID.
Returns the release number of the module hardware, preprogrammed at the factory.
js | function get_productRelease( | ) |
cpp | int get_productRelease( | ) |
m | -(int) productRelease |
pas | LongInt get_productRelease( | ): LongInt |
vb | function get_productRelease( | ) As Integer |
cs | int get_productRelease( | ) |
java | int get_productRelease( | ) |
uwp | async Task<int> get_productRelease( | ) |
py | get_productRelease( | ) |
php | function get_productRelease( | ) |
ts | async get_productRelease( | ): Promise<number> |
es | async get_productRelease( | ) |
dnp | int get_productRelease( | ) |
cp | int get_productRelease( | ) |
cmd | YModule target get_productRelease |
The original hardware release returns value 1, revision B returns value 2, etc.
Returns :
an integer corresponding to the release number of the module hardware, preprogrammed at the factory
On failure, throws an exception or returns YModule.PRODUCTRELEASE_INVALID.
Returns the remaining number of seconds before the module restarts, or zero when no reboot has been scheduled.
js | function get_rebootCountdown( | ) |
cpp | int get_rebootCountdown( | ) |
m | -(int) rebootCountdown |
pas | LongInt get_rebootCountdown( | ): LongInt |
vb | function get_rebootCountdown( | ) As Integer |
cs | int get_rebootCountdown( | ) |
java | int get_rebootCountdown( | ) |
uwp | async Task<int> get_rebootCountdown( | ) |
py | get_rebootCountdown( | ) |
php | function get_rebootCountdown( | ) |
ts | async get_rebootCountdown( | ): Promise<number> |
es | async get_rebootCountdown( | ) |
dnp | int get_rebootCountdown( | ) |
cp | int get_rebootCountdown( | ) |
cmd | YModule target get_rebootCountdown |
Returns :
an integer corresponding to the remaining number of seconds before the module restarts, or zero when no reboot has been scheduled
On failure, throws an exception or returns YModule.REBOOTCOUNTDOWN_INVALID.
Returns the serial number of the module, as set by the factory.
js | function get_serialNumber( | ) |
cpp | string get_serialNumber( | ) |
m | -(NSString*) serialNumber |
pas | string get_serialNumber( | ): string |
vb | function get_serialNumber( | ) As String |
cs | string get_serialNumber( | ) |
java | String get_serialNumber( | ) |
uwp | async Task<string> get_serialNumber( | ) |
py | get_serialNumber( | ) |
php | function get_serialNumber( | ) |
ts | async get_serialNumber( | ): Promise<string> |
es | async get_serialNumber( | ) |
dnp | string get_serialNumber( | ) |
cp | string get_serialNumber( | ) |
cmd | YModule target get_serialNumber |
Returns :
a string corresponding to the serial number of the module, as set by the factory
On failure, throws an exception or returns YModule.SERIALNUMBER_INVALID.
Returns a list of all the modules that are plugged into the current module.
js | function get_subDevices( | ) |
cpp | vector<string> get_subDevices( | ) |
m | -(NSMutableArray*) subDevices |
pas | TStringArray get_subDevices( | ): TStringArray |
vb | function get_subDevices( | ) As List |
cs | List<string> get_subDevices( | ) |
java | ArrayList<String> get_subDevices( | ) |
uwp | async Task<List<string>> get_subDevices( | ) |
py | get_subDevices( | ) |
php | function get_subDevices( | ) |
ts | async get_subDevices( | ): Promise<string[] |
es | async get_subDevices( | ) |
dnp | string[] get_subDevices( | ) |
cp | vector<string> get_subDevices( | ) |
cmd | YModule target get_subDevices |
This method only makes sense when called for a YoctoHub/VirtualHub. Otherwise, an empty array will be returned.
Returns :
an array of strings containing the sub modules.
Returns the number of milliseconds spent since the module was powered on.
js | function get_upTime( | ) |
cpp | s64 get_upTime( | ) |
m | -(s64) upTime |
pas | int64 get_upTime( | ): int64 |
vb | function get_upTime( | ) As Long |
cs | long get_upTime( | ) |
java | long get_upTime( | ) |
uwp | async Task<long> get_upTime( | ) |
py | get_upTime( | ) |
php | function get_upTime( | ) |
ts | async get_upTime( | ): Promise<number> |
es | async get_upTime( | ) |
dnp | long get_upTime( | ) |
cp | s64 get_upTime( | ) |
cmd | YModule target get_upTime |
Returns :
an integer corresponding to the number of milliseconds spent since the module was powered on
On failure, throws an exception or returns YModule.UPTIME_INVALID.
Returns the URL used to access the module.
js | function get_url( | ) |
cpp | string get_url( | ) |
m | -(NSString*) url |
pas | string get_url( | ): string |
vb | function get_url( | ) As String |
cs | string get_url( | ) |
java | String get_url( | ) |
uwp | async Task<string> get_url( | ) |
py | get_url( | ) |
php | function get_url( | ) |
ts | async get_url( | ): Promise<string> |
es | async get_url( | ) |
dnp | string get_url( | ) |
cp | string get_url( | ) |
cmd | YModule target get_url |
If the module is connected by USB, the string 'usb' is returned.
Returns :
a string with the URL of the module.
Returns the current consumed by the module on the USB bus, in milli-amps.
js | function get_usbCurrent( | ) |
cpp | int get_usbCurrent( | ) |
m | -(int) usbCurrent |
pas | LongInt get_usbCurrent( | ): LongInt |
vb | function get_usbCurrent( | ) As Integer |
cs | int get_usbCurrent( | ) |
java | int get_usbCurrent( | ) |
uwp | async Task<int> get_usbCurrent( | ) |
py | get_usbCurrent( | ) |
php | function get_usbCurrent( | ) |
ts | async get_usbCurrent( | ): Promise<number> |
es | async get_usbCurrent( | ) |
dnp | int get_usbCurrent( | ) |
cp | int get_usbCurrent( | ) |
cmd | YModule target get_usbCurrent |
Returns :
an integer corresponding to the current consumed by the module on the USB bus, in milli-amps
On failure, throws an exception or returns YModule.USBCURRENT_INVALID.
Returns the value of the userData attribute, as previously stored using method set_userData.
js | function get_userData( | ) |
cpp | void * get_userData( | ) |
m | -(id) userData |
pas | Tobject get_userData( | ): Tobject |
vb | function get_userData( | ) As Object |
cs | object get_userData( | ) |
java | Object get_userData( | ) |
py | get_userData( | ) |
php | function get_userData( | ) |
ts | async get_userData( | ): Promise<object|null> |
es | async get_userData( | ) |
This attribute is never touched directly by the API, and is at disposal of the caller to store a context.
Returns :
the object stored previously by the caller.
Returns the value previously stored in this attribute.
js | function get_userVar( | ) |
cpp | int get_userVar( | ) |
m | -(int) userVar |
pas | LongInt get_userVar( | ): LongInt |
vb | function get_userVar( | ) As Integer |
cs | int get_userVar( | ) |
java | int get_userVar( | ) |
uwp | async Task<int> get_userVar( | ) |
py | get_userVar( | ) |
php | function get_userVar( | ) |
ts | async get_userVar( | ): Promise<number> |
es | async get_userVar( | ) |
dnp | int get_userVar( | ) |
cp | int get_userVar( | ) |
cmd | YModule target get_userVar |
On startup and after a device reboot, the value is always reset to zero.
Returns :
an integer corresponding to the value previously stored in this attribute
On failure, throws an exception or returns YModule.USERVAR_INVALID.
Tests if the device includes a specific function.
js | function hasFunction( | funcId) |
cpp | bool hasFunction( | string funcId) |
m | -(bool) hasFunction | : (NSString*) funcId |
pas | boolean hasFunction( | funcId: string): boolean |
vb | function hasFunction( | ByVal funcId As String) As Boolean |
cs | bool hasFunction( | string funcId) |
java | boolean hasFunction( | String funcId) |
uwp | async Task<bool> hasFunction( | string funcId) |
py | hasFunction( | funcId) |
php | function hasFunction( | $funcId) |
ts | async hasFunction( | funcId: string): Promise<boolean> |
es | async hasFunction( | funcId) |
dnp | bool hasFunction( | string funcId) |
cp | bool hasFunction( | string funcId) |
cmd | YModule target hasFunction | funcId |
This method takes a function identifier and returns a boolean.
Parameters :
funcId | the requested function identifier |
Returns :
true if the device has the function identifier
Checks if the module is currently reachable, without raising any error.
js | function isOnline( | ) |
cpp | bool isOnline( | ) |
m | -(BOOL) isOnline |
pas | boolean isOnline( | ): boolean |
vb | function isOnline( | ) As Boolean |
cs | bool isOnline( | ) |
java | boolean isOnline( | ) |
py | isOnline( | ) |
php | function isOnline( | ) |
ts | async isOnline( | ): Promise<boolean> |
es | async isOnline( | ) |
dnp | bool isOnline( | ) |
cp | bool isOnline( | ) |
If there are valid cached values for the module, that have not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the requested module.
Returns :
true if the module can be reached, and false otherwise
Checks if the module is currently reachable, without raising any error.
js | function isOnline_async( | callback, context) |
If there are valid cached values for the module, that have not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the requested module.
This asynchronous version exists only in JavaScript. It uses a callback instead of a return value in order to avoid blocking Firefox JavaScript VM that does not implement context switching during blocking I/O calls.
Parameters :
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving module object and the boolean result |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Preloads the module cache with a specified validity duration.
js | function load( | msValidity) |
cpp | YRETCODE load( | int msValidity) |
m | -(YRETCODE) load | : (u64) msValidity |
pas | YRETCODE load( | msValidity: u64): YRETCODE |
vb | function load( | ByVal msValidity As Long) As YRETCODE |
cs | YRETCODE load( | ulong msValidity) |
java | int load( | long msValidity) |
py | load( | msValidity) |
php | function load( | $msValidity) |
ts | async load( | msValidity: number): Promise<number> |
es | async load( | msValidity) |
By default, whenever accessing a device, all module attributes are kept in cache for the standard duration (5 ms). This method can be used to temporarily mark the cache as valid for a longer period, in order to reduce network traffic for instance.
Parameters :
msValidity | an integer corresponding to the validity attributed to the loaded module parameters, in milliseconds |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Preloads the module cache with a specified validity duration (asynchronous version).
js | function load_async( | msValidity, callback, context) |
By default, whenever accessing a device, all module attributes are kept in cache for the standard duration (5 ms). This method can be used to temporarily mark the cache as valid for a longer period, in order to reduce network traffic for instance.
This asynchronous version exists only in JavaScript. It uses a callback instead of a return value in order to avoid blocking Firefox JavaScript VM that does not implement context switching during blocking I/O calls. See the documentation section on asynchronous JavaScript calls for more details.
Parameters :
msValidity | an integer corresponding to the validity of the loaded module parameters, in milliseconds |
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving module object and the error code (or YAPI.SUCCESS) |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Adds a text message to the device logs.
js | function log( | text) |
cpp | int log( | string text) |
m | -(int) log | : (NSString*) text |
pas | LongInt log( | text: string): LongInt |
vb | function log( | ByVal text As String) As Integer |
cs | int log( | string text) |
java | int log( | String text) |
uwp | async Task<int> log( | string text) |
py | log( | text) |
php | function log( | $text) |
ts | async log( | text: string): Promise<number> |
es | async log( | text) |
dnp | int log( | string text) |
cp | int log( | string text) |
cmd | YModule target log | text |
This function is useful in particular to trace the execution of HTTP callbacks. If a newline is desired after the message, it must be included in the string.
Parameters :
text | the string to append to the logs. |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Continues the module enumeration started using yFirstModule().
js | function nextModule( | ) |
cpp | YModule * nextModule( | ) |
m | -(nullable YModule*) nextModule |
pas | TYModule nextModule( | ): TYModule |
vb | function nextModule( | ) As YModule |
cs | YModule nextModule( | ) |
java | YModule nextModule( | ) |
uwp | YModule nextModule( | ) |
py | nextModule( | ) |
php | function nextModule( | ) |
ts | nextModule( | ): YModule | null |
es | nextModule( | ) |
Caution: You can't make any assumption about the returned modules order. If you want to find a specific module, use Module.findModule() and a hardwareID or a logical name.
Returns :
a pointer to a YModule object, corresponding to the next module found, or a null pointer if there are no more modules to enumerate.
Schedules a simple module reboot after the given number of seconds.
js | function reboot( | secBeforeReboot) |
cpp | int reboot( | int secBeforeReboot) |
m | -(int) reboot | : (int) secBeforeReboot |
pas | LongInt reboot( | secBeforeReboot: LongInt): LongInt |
vb | function reboot( | ByVal secBeforeReboot As Integer) As Integer |
cs | int reboot( | int secBeforeReboot) |
java | int reboot( | int secBeforeReboot) |
uwp | async Task<int> reboot( | int secBeforeReboot) |
py | reboot( | secBeforeReboot) |
php | function reboot( | $secBeforeReboot) |
ts | async reboot( | secBeforeReboot: number): Promise<number> |
es | async reboot( | secBeforeReboot) |
dnp | int reboot( | int secBeforeReboot) |
cp | int reboot( | int secBeforeReboot) |
cmd | YModule target reboot | secBeforeReboot |
Parameters :
secBeforeReboot | number of seconds before rebooting |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Register a callback function, to be called when the localization beacon of the module has been changed.
js | function registerBeaconCallback( | callback) |
cpp | int registerBeaconCallback( | YModuleBeaconCallback callback) |
m | -(int) registerBeaconCallback | : (YModuleBeaconCallback _Nullable) callback |
pas | LongInt registerBeaconCallback( | callback: TYModuleBeaconCallback): LongInt |
vb | function registerBeaconCallback( | ByVal callback As YModuleBeaconCallback) As Integer |
cs | int registerBeaconCallback( | BeaconCallback callback) |
java | int registerBeaconCallback( | BeaconCallback callback) |
uwp | async Task<int> registerBeaconCallback( | BeaconCallback callback) |
py | registerBeaconCallback( | callback) |
php | function registerBeaconCallback( | $callback) |
ts | async registerBeaconCallback( | callback: YModuleBeaconCallback | null): Promise<number> |
es | async registerBeaconCallback( | callback) |
The callback function should take two arguments: the YModule object of which the beacon has changed, and an integer describing the new beacon state.
Parameters :
callback | The callback function to call, or null to unregister a |
Register a callback function, to be called when a persistent settings in a device configuration has been changed (e.g.
js | function registerConfigChangeCallback( | callback) |
cpp | int registerConfigChangeCallback( | YModuleConfigChangeCallback callback) |
m | -(int) registerConfigChangeCallback | : (YModuleConfigChangeCallback _Nullable) callback |
pas | LongInt registerConfigChangeCallback( | callback: TYModuleConfigChangeCallback): LongInt |
vb | function registerConfigChangeCallback( | ByVal callback As YModuleConfigChangeCallback) As Integer |
cs | int registerConfigChangeCallback( | ConfigChangeCallback callback) |
java | int registerConfigChangeCallback( | ConfigChangeCallback callback) |
uwp | async Task<int> registerConfigChangeCallback( | ConfigChangeCallback callback) |
py | registerConfigChangeCallback( | callback) |
php | function registerConfigChangeCallback( | $callback) |
ts | async registerConfigChangeCallback( | callback: YModuleConfigChangeCallback | null): Promise<number> |
es | async registerConfigChangeCallback( | callback) |
change of unit, etc).
Parameters :
callback | a procedure taking a YModule parameter, or null |
Registers a device log callback function.
js | function registerLogCallback( | callback) |
cpp | int registerLogCallback( | YModuleLogCallback callback) |
m | -(int) registerLogCallback | : (YModuleLogCallback _Nullable) callback |
pas | LongInt registerLogCallback( | callback: TYModuleLogCallback): LongInt |
vb | function registerLogCallback( | ByVal callback As YModuleLogCallback) As Integer |
cs | int registerLogCallback( | LogCallback callback) |
java | int registerLogCallback( | LogCallback callback) |
uwp | async Task<int> registerLogCallback( | LogCallback callback) |
py | registerLogCallback( | callback) |
php | function registerLogCallback( | $callback) |
ts | async registerLogCallback( | callback: YModuleLogCallback | null): Promise<number> |
es | async registerLogCallback( | callback) |
This callback will be called each time that a module sends a new log message. Mostly useful to debug a Yoctopuce module.
Parameters :
callback | the callback function to call, or a null pointer. The callback function should take two arguments: the module object that emitted the log message, and the character string containing the log. |
Reloads the settings stored in the nonvolatile memory, as when the module is powered on.
js | function revertFromFlash( | ) |
cpp | int revertFromFlash( | ) |
m | -(int) revertFromFlash |
pas | LongInt revertFromFlash( | ): LongInt |
vb | function revertFromFlash( | ) As Integer |
cs | int revertFromFlash( | ) |
java | int revertFromFlash( | ) |
uwp | async Task<int> revertFromFlash( | ) |
py | revertFromFlash( | ) |
php | function revertFromFlash( | ) |
ts | async revertFromFlash( | ): Promise<number> |
es | async revertFromFlash( | ) |
dnp | int revertFromFlash( | ) |
cp | int revertFromFlash( | ) |
cmd | YModule target revertFromFlash |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Saves current settings in the nonvolatile memory of the module.
js | function saveToFlash( | ) |
cpp | int saveToFlash( | ) |
m | -(int) saveToFlash |
pas | LongInt saveToFlash( | ): LongInt |
vb | function saveToFlash( | ) As Integer |
cs | int saveToFlash( | ) |
java | int saveToFlash( | ) |
uwp | async Task<int> saveToFlash( | ) |
py | saveToFlash( | ) |
php | function saveToFlash( | ) |
ts | async saveToFlash( | ): Promise<number> |
es | async saveToFlash( | ) |
dnp | int saveToFlash( | ) |
cp | int saveToFlash( | ) |
cmd | YModule target saveToFlash |
Warning: the number of allowed save operations during a module life is limited (about 100000 cycles). Do not call this function within a loop.
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Restores all the settings of the device.
js | function set_allSettings( | settings) |
cpp | int set_allSettings( | string settings) |
m | -(int) setAllSettings | : (NSData*) settings |
pas | LongInt set_allSettings( | settings: TByteArray): LongInt |
vb | procedure set_allSettings( | ByVal settings As Byte() |
cs | int set_allSettings( | byte[] settings) |
java | int set_allSettings( | byte[] settings) |
uwp | async Task<int> set_allSettings( | byte[] settings) |
py | set_allSettings( | settings) |
php | function set_allSettings( | $settings) |
ts | async set_allSettings( | settings: Uint8Array): Promise<number> |
es | async set_allSettings( | settings) |
dnp | int set_allSettings( | byte[] settings) |
cp | int set_allSettings( | string settings) |
cmd | YModule target set_allSettings | settings |
Useful to restore all the logical names and calibrations parameters of a module from a backup.Remember to call the saveToFlash() method of the module if the modifications must be kept.
Parameters :
settings | a binary buffer with all the settings. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Restores all the settings and uploaded files to the module.
js | function set_allSettingsAndFiles( | settings) |
cpp | int set_allSettingsAndFiles( | string settings) |
m | -(int) setAllSettingsAndFiles | : (NSData*) settings |
pas | LongInt set_allSettingsAndFiles( | settings: TByteArray): LongInt |
vb | procedure set_allSettingsAndFiles( | ByVal settings As Byte() |
cs | int set_allSettingsAndFiles( | byte[] settings) |
java | int set_allSettingsAndFiles( | byte[] settings) |
uwp | async Task<int> set_allSettingsAndFiles( | byte[] settings) |
py | set_allSettingsAndFiles( | settings) |
php | function set_allSettingsAndFiles( | $settings) |
ts | async set_allSettingsAndFiles( | settings: Uint8Array): Promise<number> |
es | async set_allSettingsAndFiles( | settings) |
dnp | int set_allSettingsAndFiles( | byte[] settings) |
cp | int set_allSettingsAndFiles( | string settings) |
cmd | YModule target set_allSettingsAndFiles | settings |
This method is useful to restore all the logical names and calibrations parameters, uploaded files etc. of a device from a backup. Remember to call the saveToFlash() method of the module if the modifications must be kept.
Parameters :
settings | a binary buffer with all the settings. |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Turns on or off the module localization beacon.
js | function set_beacon( | newval) |
cpp | int set_beacon( | Y_BEACON_enum newval) |
m | -(int) setBeacon | : (Y_BEACON_enum) newval |
pas | integer set_beacon( | newval: Integer): integer |
vb | function set_beacon( | ByVal newval As Integer) As Integer |
cs | int set_beacon( | int newval) |
java | int set_beacon( | int newval) |
uwp | async Task<int> set_beacon( | int newval) |
py | set_beacon( | newval) |
php | function set_beacon( | $newval) |
ts | async set_beacon( | newval: YModule_Beacon): Promise<number> |
es | async set_beacon( | newval) |
dnp | int set_beacon( | int newval) |
cp | int set_beacon( | int newval) |
cmd | YModule target set_beacon | newval |
Parameters :
newval | either YModule.BEACON_OFF or YModule.BEACON_ON |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the logical name of the module.
js | function set_logicalName( | newval) |
cpp | int set_logicalName( | string newval) |
m | -(int) setLogicalName | : (NSString*) newval |
pas | integer set_logicalName( | newval: string): integer |
vb | function set_logicalName( | ByVal newval As String) As Integer |
cs | int set_logicalName( | string newval) |
java | int set_logicalName( | String newval) |
uwp | async Task<int> set_logicalName( | string newval) |
py | set_logicalName( | newval) |
php | function set_logicalName( | $newval) |
ts | async set_logicalName( | newval: string): Promise<number> |
es | async set_logicalName( | newval) |
dnp | int set_logicalName( | string newval) |
cp | int set_logicalName( | string newval) |
cmd | YModule target set_logicalName | newval |
You can use yCheckLogicalName() prior to this call to make sure that your parameter is valid. Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | a string corresponding to the logical name of the module |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the luminosity of the module informative leds.
js | function set_luminosity( | newval) |
cpp | int set_luminosity( | int newval) |
m | -(int) setLuminosity | : (int) newval |
pas | integer set_luminosity( | newval: LongInt): integer |
vb | function set_luminosity( | ByVal newval As Integer) As Integer |
cs | int set_luminosity( | int newval) |
java | int set_luminosity( | int newval) |
uwp | async Task<int> set_luminosity( | int newval) |
py | set_luminosity( | newval) |
php | function set_luminosity( | $newval) |
ts | async set_luminosity( | newval: number): Promise<number> |
es | async set_luminosity( | newval) |
dnp | int set_luminosity( | int newval) |
cp | int set_luminosity( | int newval) |
cmd | YModule target set_luminosity | newval |
The parameter is a value between 0 and 100. Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | an integer corresponding to the luminosity of the module informative leds |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Stores a user context provided as argument in the userData attribute of the function.
js | function set_userData( | data) |
cpp | void set_userData( | void * data) |
m | -(void) setUserData | : (id) data |
pas | set_userData( | data: Tobject) |
vb | procedure set_userData( | ByVal data As Object) |
cs | void set_userData( | object data) |
java | void set_userData( | Object data) |
py | set_userData( | data) |
php | function set_userData( | $data) |
ts | async set_userData( | data: object|null): Promise<void> |
es | async set_userData( | data) |
This attribute is never touched by the API, and is at disposal of the caller to store a context.
Parameters :
data | any kind of object to be stored |
Stores a 32 bit value in the device RAM.
js | function set_userVar( | newval) |
cpp | int set_userVar( | int newval) |
m | -(int) setUserVar | : (int) newval |
pas | integer set_userVar( | newval: LongInt): integer |
vb | function set_userVar( | ByVal newval As Integer) As Integer |
cs | int set_userVar( | int newval) |
java | int set_userVar( | int newval) |
uwp | async Task<int> set_userVar( | int newval) |
py | set_userVar( | newval) |
php | function set_userVar( | $newval) |
ts | async set_userVar( | newval: number): Promise<number> |
es | async set_userVar( | newval) |
dnp | int set_userVar( | int newval) |
cp | int set_userVar( | int newval) |
cmd | YModule target set_userVar | newval |
This attribute is at programmer disposal, should he need to store a state variable. On startup and after a device reboot, the value is always reset to zero.
Parameters :
newval | an integer |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Triggers a configuration change callback, to check if they are supported or not.
js | function triggerConfigChangeCallback( | ) |
cpp | int triggerConfigChangeCallback( | ) |
m | -(int) triggerConfigChangeCallback |
pas | LongInt triggerConfigChangeCallback( | ): LongInt |
vb | function triggerConfigChangeCallback( | ) As Integer |
cs | int triggerConfigChangeCallback( | ) |
java | int triggerConfigChangeCallback( | ) |
uwp | async Task<int> triggerConfigChangeCallback( | ) |
py | triggerConfigChangeCallback( | ) |
php | function triggerConfigChangeCallback( | ) |
ts | async triggerConfigChangeCallback( | ): Promise<number> |
es | async triggerConfigChangeCallback( | ) |
dnp | int triggerConfigChangeCallback( | ) |
cp | int triggerConfigChangeCallback( | ) |
cmd | YModule target triggerConfigChangeCallback |
Schedules a module reboot into special firmware update mode.
js | function triggerFirmwareUpdate( | secBeforeReboot) |
cpp | int triggerFirmwareUpdate( | int secBeforeReboot) |
m | -(int) triggerFirmwareUpdate | : (int) secBeforeReboot |
pas | LongInt triggerFirmwareUpdate( | secBeforeReboot: LongInt): LongInt |
vb | function triggerFirmwareUpdate( | ByVal secBeforeReboot As Integer) As Integer |
cs | int triggerFirmwareUpdate( | int secBeforeReboot) |
java | int triggerFirmwareUpdate( | int secBeforeReboot) |
uwp | async Task<int> triggerFirmwareUpdate( | int secBeforeReboot) |
py | triggerFirmwareUpdate( | secBeforeReboot) |
php | function triggerFirmwareUpdate( | $secBeforeReboot) |
ts | async triggerFirmwareUpdate( | secBeforeReboot: number): Promise<number> |
es | async triggerFirmwareUpdate( | secBeforeReboot) |
dnp | int triggerFirmwareUpdate( | int secBeforeReboot) |
cp | int triggerFirmwareUpdate( | int secBeforeReboot) |
cmd | YModule target triggerFirmwareUpdate | secBeforeReboot |
Parameters :
secBeforeReboot | number of seconds before rebooting |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Prepares a firmware update of the module.
js | function updateFirmware( | path) |
cpp | YFirmwareUpdate updateFirmware( | string path) |
m | -(YFirmwareUpdate*) updateFirmware | : (NSString*) path |
pas | TYFirmwareUpdate updateFirmware( | path: string): TYFirmwareUpdate |
vb | function updateFirmware( | ByVal path As String) As YFirmwareUpdate |
cs | YFirmwareUpdate updateFirmware( | string path) |
java | YFirmwareUpdate updateFirmware( | String path) |
uwp | async Task<YFirmwareUpdate> updateFirmware( | string path) |
py | updateFirmware( | path) |
php | function updateFirmware( | $path) |
ts | async updateFirmware( | path: string): Promise<YFirmwareUpdate> |
es | async updateFirmware( | path) |
dnp | YFirmwareUpdateProxy updateFirmware( | string path) |
cp | YFirmwareUpdateProxy* updateFirmware( | string path) |
cmd | YModule target updateFirmware | path |
This method returns a YFirmwareUpdate object which handles the firmware update process.
Parameters :
path | the path of the .byn file to use. |
Returns :
a YFirmwareUpdate object or NULL on error.
Prepares a firmware update of the module.
js | function updateFirmwareEx( | path, force) |
cpp | YFirmwareUpdate updateFirmwareEx( | string path, bool force) |
m | -(YFirmwareUpdate*) updateFirmwareEx | : (NSString*) path |
: (bool) force |
pas | TYFirmwareUpdate updateFirmwareEx( | path: string, force: boolean): TYFirmwareUpdate |
vb | function updateFirmwareEx( | ByVal path As String, |
ByVal force As Boolean) As YFirmwareUpdate |
cs | YFirmwareUpdate updateFirmwareEx( | string path, bool force) |
java | YFirmwareUpdate updateFirmwareEx( | String path, boolean force) |
uwp | async Task<YFirmwareUpdate> updateFirmwareEx( | string path, bool force) |
py | updateFirmwareEx( | path, force) |
php | function updateFirmwareEx( | $path, $force) |
ts | async updateFirmwareEx( | path: string, force: boolean): Promise<YFirmwareUpdate> |
es | async updateFirmwareEx( | path, force) |
dnp | YFirmwareUpdateProxy updateFirmwareEx( | string path, bool force) |
cp | YFirmwareUpdateProxy* updateFirmwareEx( | string path, |
bool force) |
cmd | YModule target updateFirmwareEx | path force |
This method returns a YFirmwareUpdate object which handles the firmware update process.
Parameters :
path | the path of the .byn file to use. |
force | true to force the firmware update even if some prerequisites appear not to be met |
Returns :
a YFirmwareUpdate object or NULL on error.
Waits for all pending asynchronous commands on the module to complete, and invoke the user-provided callback function.
js | function wait_async( | callback, context) |
ts | wait_async( | callback: Function, context: object) |
es | wait_async( | callback, context) |
The callback function can therefore freely issue synchronous or asynchronous commands, without risking to block the JavaScript VM.
Parameters :
callback | callback function that is invoked when all pending commands on the module are completed. The callback function receives two arguments: the caller-specific context object and the receiving function object. |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing.
Analog input control interface, available for instance in the Yocto-Buzzer, the Yocto-Knob, the Yocto-MaxiBuzzer or the Yocto-MaxiDisplay
The YAnButton class provide access to basic resistive inputs. Such inputs can be used to measure the state of a simple button as well as to read an analog potentiometer (variable resistance). This can be use for instance with a continuous rotating knob, a throttle grip or a joystick. The module is capable to calibrate itself on min and max values, in order to compute a calibrated value that varies proportionally with the potentiometer position, regardless of its total resistance.
In order to use the functions described here, you should include:
es | in HTML: <script src="../../lib/yocto_anbutton.js"></script> in node.js: require('yoctolib-es2017/yocto_anbutton.js'); |
js | <script type='text/javascript' src='yocto_anbutton.js'></script> |
cpp | #include "yocto_anbutton.h" |
m | #import "yocto_anbutton.h" |
pas | uses yocto_anbutton; |
vb | yocto_anbutton.vb |
cs | yocto_anbutton.cs |
java | import com.yoctopuce.YoctoAPI.YAnButton; |
uwp | import com.yoctopuce.YoctoAPI.YAnButton; |
py | from yocto_anbutton import * |
php | require_once('yocto_anbutton.php'); |
ts | in HTML: import { YAnButton } from '../../dist/esm/yocto_anbutton.js'; in Node.js: import { YAnButton } from 'yoctolib-cjs/yocto_anbutton.js'; |
dnp | import YoctoProxyAPI.YAnButtonProxy |
cp | #include "yocto_anbutton_proxy.h" |
vi | YAnButton.vi |
ml | import YoctoProxyAPI.YAnButtonProxy |
Global functions |
---|
YAnButton.FindAnButton(func) |
Retrieves an analog input for a given identifier. |
YAnButton.FindAnButtonInContext(yctx, func) |
Retrieves an analog input for a given identifier in a YAPI context. |
YAnButton.FirstAnButton() |
Starts the enumeration of analog inputs currently accessible. |
YAnButton.FirstAnButtonInContext(yctx) |
Starts the enumeration of analog inputs currently accessible. |
YAnButton.GetSimilarFunctions() |
Enumerates all functions of type AnButton available on the devices currently reachable by the library, and returns their unique hardware ID. |
YAnButton properties |
anbutton→AdvertisedValue [read-only] |
Short string representing the current state of the function. |
anbutton→AnalogCalibration [writable] |
Tells if a calibration process is currently ongoing. |
anbutton→CalibratedValue [read-only] |
Current calibrated input value (between 0 and 1000, included). |
anbutton→CalibrationMax [writable] |
Maximal value measured during the calibration (between 0 and 4095, included). |
anbutton→CalibrationMin [writable] |
Minimal value measured during the calibration (between 0 and 4095, included). |
anbutton→FriendlyName [read-only] |
Global identifier of the function in the format MODULE_NAME.FUNCTION_NAME. |
anbutton→FunctionId [read-only] |
Hardware identifier of the analog input, without reference to the module. |
anbutton→HardwareId [read-only] |
Unique hardware identifier of the function in the form SERIAL.FUNCTIONID. |
anbutton→InputType [writable] |
Decoding method applied to the input (analog or multiplexed binary switches). |
anbutton→IsOnline [read-only] |
Checks if the function is currently reachable. |
anbutton→IsPressed [read-only] |
True if the input (considered as binary) is active (closed contact), and false otherwise. |
anbutton→LogicalName [writable] |
Logical name of the function. |
anbutton→Sensitivity [writable] |
Sensibility for the input (between 1 and 1000) for triggering user callbacks. |
anbutton→SerialNumber [read-only] |
Serial number of the module, as set by the factory. |
YAnButton methods |
anbutton→clearCache() |
Invalidates the cache. |
anbutton→describe() |
Returns a short text that describes unambiguously the instance of the analog input in the form TYPE(NAME)=SERIAL.FUNCTIONID. |
anbutton→get_advertisedValue() |
Returns the current value of the analog input (no more than 6 characters). |
anbutton→get_analogCalibration() |
Tells if a calibration process is currently ongoing. |
anbutton→get_calibratedValue() |
Returns the current calibrated input value (between 0 and 1000, included). |
anbutton→get_calibrationMax() |
Returns the maximal value measured during the calibration (between 0 and 4095, included). |
anbutton→get_calibrationMin() |
Returns the minimal value measured during the calibration (between 0 and 4095, included). |
anbutton→get_errorMessage() |
Returns the error message of the latest error with the analog input. |
anbutton→get_errorType() |
Returns the numerical error code of the latest error with the analog input. |
anbutton→get_friendlyName() |
Returns a global identifier of the analog input in the format MODULE_NAME.FUNCTION_NAME. |
anbutton→get_functionDescriptor() |
Returns a unique identifier of type YFUN_DESCR corresponding to the function. |
anbutton→get_functionId() |
Returns the hardware identifier of the analog input, without reference to the module. |
anbutton→get_hardwareId() |
Returns the unique hardware identifier of the analog input in the form SERIAL.FUNCTIONID. |
anbutton→get_inputType() |
Returns the decoding method applied to the input (analog or multiplexed binary switches). |
anbutton→get_isPressed() |
Returns true if the input (considered as binary) is active (closed contact), and false otherwise. |
anbutton→get_lastTimePressed() |
Returns the number of elapsed milliseconds between the module power on and the last time the input button was pressed (the input contact transitioned from open to closed). |
anbutton→get_lastTimeReleased() |
Returns the number of elapsed milliseconds between the module power on and the last time the input button was released (the input contact transitioned from closed to open). |
anbutton→get_logicalName() |
Returns the logical name of the analog input. |
anbutton→get_module() |
Gets the YModule object for the device on which the function is located. |
anbutton→get_module_async(callback, context) |
Gets the YModule object for the device on which the function is located (asynchronous version). |
anbutton→get_pulseCounter() |
Returns the pulse counter value. |
anbutton→get_pulseTimer() |
Returns the timer of the pulses counter (ms). |
anbutton→get_rawValue() |
Returns the current measured input value as-is (between 0 and 4095, included). |
anbutton→get_sensitivity() |
Returns the sensibility for the input (between 1 and 1000) for triggering user callbacks. |
anbutton→get_serialNumber() |
Returns the serial number of the module, as set by the factory. |
anbutton→get_userData() |
Returns the value of the userData attribute, as previously stored using method set_userData. |
anbutton→isOnline() |
Checks if the analog input is currently reachable, without raising any error. |
anbutton→isOnline_async(callback, context) |
Checks if the analog input is currently reachable, without raising any error (asynchronous version). |
anbutton→isReadOnly() |
Test if the function is readOnly. |
anbutton→load(msValidity) |
Preloads the analog input cache with a specified validity duration. |
anbutton→loadAttribute(attrName) |
Returns the current value of a single function attribute, as a text string, as quickly as possible but without using the cached value. |
anbutton→load_async(msValidity, callback, context) |
Preloads the analog input cache with a specified validity duration (asynchronous version). |
anbutton→muteValueCallbacks() |
Disables the propagation of every new advertised value to the parent hub. |
anbutton→nextAnButton() |
Continues the enumeration of analog inputs started using yFirstAnButton(). |
anbutton→registerValueCallback(callback) |
Registers the callback function that is invoked on every change of advertised value. |
anbutton→resetCounter() |
Returns the pulse counter value as well as its timer. |
anbutton→set_analogCalibration(newval) |
Starts or stops the calibration process. |
anbutton→set_calibrationMax(newval) |
Changes the maximal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration. |
anbutton→set_calibrationMin(newval) |
Changes the minimal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration. |
anbutton→set_inputType(newval) |
Changes the decoding method applied to the input (analog or multiplexed binary switches). |
anbutton→set_logicalName(newval) |
Changes the logical name of the analog input. |
anbutton→set_sensitivity(newval) |
Changes the sensibility for the input (between 1 and 1000) for triggering user callbacks. |
anbutton→set_userData(data) |
Stores a user context provided as argument in the userData attribute of the function. |
anbutton→unmuteValueCallbacks() |
Re-enables the propagation of every new advertised value to the parent hub. |
anbutton→wait_async(callback, context) |
Waits for all pending asynchronous commands on the module to complete, and invoke the user-provided callback function. |
Retrieves an analog input for a given identifier.
js | function yFindAnButton( | func) |
cpp | YAnButton* FindAnButton( | string func) |
m | +(YAnButton*) FindAnButton | : (NSString*) func |
pas | TYAnButton yFindAnButton( | func: string): TYAnButton |
vb | function FindAnButton( | ByVal func As String) As YAnButton |
cs | static YAnButton FindAnButton( | string func) |
java | static YAnButton FindAnButton( | String func) |
uwp | static YAnButton FindAnButton( | string func) |
py | FindAnButton( | func) |
php | function FindAnButton( | $func) |
ts | static FindAnButton( | func: string): YAnButton |
es | static FindAnButton( | func) |
dnp | static YAnButtonProxy FindAnButton( | string func) |
cp | static YAnButtonProxy * FindAnButton( | string func) |
The identifier can be specified using several formats:
This function does not require that the analog input is online at the time it is invoked. The returned object is nevertheless valid. Use the method YAnButton.isOnline() to test if the analog input is indeed online at a given time. In case of ambiguity when looking for an analog input by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.
If a call to this object's is_online() method returns FALSE although you are certain that the matching device is plugged, make sure that you did call registerHub() at application initialization time.
Parameters :
func | a string that uniquely characterizes the analog input, for instance YBUZZER2.anButton1. |
Returns :
a YAnButton object allowing you to drive the analog input.
Retrieves an analog input for a given identifier in a YAPI context.
java | static YAnButton FindAnButtonInContext( | YAPIContext yctx, String func) |
uwp | static YAnButton FindAnButtonInContext( | YAPIContext yctx, string func) |
ts | static FindAnButtonInContext( | yctx: YAPIContext, func: string): YAnButton |
es | static FindAnButtonInContext( | yctx, func) |
The identifier can be specified using several formats:
This function does not require that the analog input is online at the time it is invoked. The returned object is nevertheless valid. Use the method YAnButton.isOnline() to test if the analog input is indeed online at a given time. In case of ambiguity when looking for an analog input by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.
Parameters :
yctx | a YAPI context |
func | a string that uniquely characterizes the analog input, for instance YBUZZER2.anButton1. |
Returns :
a YAnButton object allowing you to drive the analog input.
Starts the enumeration of analog inputs currently accessible.
js | function yFirstAnButton( | ) |
cpp | YAnButton * FirstAnButton( | ) |
m | +(YAnButton*) FirstAnButton |
pas | TYAnButton yFirstAnButton( | ): TYAnButton |
vb | function FirstAnButton( | ) As YAnButton |
cs | static YAnButton FirstAnButton( | ) |
java | static YAnButton FirstAnButton( | ) |
uwp | static YAnButton FirstAnButton( | ) |
py | FirstAnButton( | ) |
php | function FirstAnButton( | ) |
ts | static FirstAnButton( | ): YAnButton | null |
es | static FirstAnButton( | ) |
Use the method YAnButton.nextAnButton() to iterate on next analog inputs.
Returns :
a pointer to a YAnButton object, corresponding to the first analog input currently online, or a null pointer if there are none.
Starts the enumeration of analog inputs currently accessible.
java | static YAnButton FirstAnButtonInContext( | YAPIContext yctx) |
uwp | static YAnButton FirstAnButtonInContext( | YAPIContext yctx) |
ts | static FirstAnButtonInContext( | yctx: YAPIContext): YAnButton | null |
es | static FirstAnButtonInContext( | yctx) |
Use the method YAnButton.nextAnButton() to iterate on next analog inputs.
Parameters :
yctx | a YAPI context. |
Returns :
a pointer to a YAnButton object, corresponding to the first analog input currently online, or a null pointer if there are none.
Enumerates all functions of type AnButton available on the devices currently reachable by the library, and returns their unique hardware ID.
dnp | static new string[] GetSimilarFunctions( | ) |
cp | static vector<string> GetSimilarFunctions( | ) |
Each of these IDs can be provided as argument to the method YAnButton.FindAnButton to obtain an object that can control the corresponding device.
Returns :
an array of strings, each string containing the unique hardwareId of a device function currently connected.
Short string representing the current state of the function.
dnp | string AdvertisedValue |
Tells if a calibration process is currently ongoing.
dnp | int AnalogCalibration |
Writable. Starts or stops the calibration process. Remember to call the saveToFlash() method of the module at the end of the calibration if the modification must be kept.
Current calibrated input value (between 0 and 1000, included).
dnp | int CalibratedValue |
Maximal value measured during the calibration (between 0 and 4095, included).
dnp | int CalibrationMax |
Writable. Changes the maximal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration. Remember to call the saveToFlash() method of the module if the modification must be kept.
Minimal value measured during the calibration (between 0 and 4095, included).
dnp | int CalibrationMin |
Writable. Changes the minimal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration. Remember to call the saveToFlash() method of the module if the modification must be kept.
Global identifier of the function in the format MODULE_NAME.FUNCTION_NAME.
dnp | string FriendlyName |
The returned string uses the logical names of the module and of the function if they are defined, otherwise the serial number of the module and the hardware identifier of the function (for example: MyCustomName.relay1)
Hardware identifier of the analog input, without reference to the module.
dnp | string FunctionId |
For example relay1
Unique hardware identifier of the function in the form SERIAL.FUNCTIONID.
dnp | string HardwareId |
The unique hardware identifier is composed of the device serial number and of the hardware identifier of the function (for example RELAYLO1-123456.relay1).
Decoding method applied to the input (analog or multiplexed binary switches).
dnp | int InputType |
Writable. Remember to call the saveToFlash() method of the module if the modification must be kept.
Checks if the function is currently reachable.
dnp | bool IsOnline |
If there is a cached value for the function in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the function.
True if the input (considered as binary) is active (closed contact), and false otherwise.
dnp | int IsPressed |
Logical name of the function.
dnp | string LogicalName |
Writable. You can use yCheckLogicalName() prior to this call to make sure that your parameter is valid. Remember to call the saveToFlash() method of the module if the modification must be kept.
Sensibility for the input (between 1 and 1000) for triggering user callbacks.
dnp | int Sensitivity |
Writable. The sensibility is used to filter variations around a fixed value, but does not preclude the transmission of events when the input value evolves constantly in the same direction. Special case: when the value 1000 is used, the callback will only be thrown when the logical state of the input switches from pressed to released and back. Remember to call the saveToFlash() method of the module if the modification must be kept.
Serial number of the module, as set by the factory.
dnp | string SerialNumber |
Invalidates the cache.
js | function clearCache( | ) |
cpp | void clearCache( | ) |
m | -(void) clearCache |
pas | clearCache( | ) |
vb | procedure clearCache( | ) |
cs | void clearCache( | ) |
java | void clearCache( | ) |
py | clearCache( | ) |
php | function clearCache( | ) |
ts | async clearCache( | ): Promise<void> |
es | async clearCache( | ) |
Invalidates the cache of the analog input attributes. Forces the next call to get_xxx() or loadxxx() to use values that come from the device.
Returns a short text that describes unambiguously the instance of the analog input in the form TYPE(NAME)=SERIAL.FUNCTIONID.
js | function describe( | ) |
cpp | string describe( | ) |
m | -(NSString*) describe |
pas | string describe( | ): string |
vb | function describe( | ) As String |
cs | string describe( | ) |
java | String describe( | ) |
py | describe( | ) |
php | function describe( | ) |
ts | async describe( | ): Promise<string> |
es | async describe( | ) |
More precisely, TYPE is the type of the function, NAME it the name used for the first access to the function, SERIAL is the serial number of the module if the module is connected or "unresolved", and FUNCTIONID is the hardware identifier of the function if the module is connected. For example, this method returns Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1 if the module is already connected or Relay(BadCustomeName.relay1)=unresolved if the module has not yet been connected. This method does not trigger any USB or TCP transaction and can therefore be used in a debugger.
Returns :
a string that describes the analog input (ex: Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1)
Returns the current value of the analog input (no more than 6 characters).
js | function get_advertisedValue( | ) |
cpp | string get_advertisedValue( | ) |
m | -(NSString*) advertisedValue |
pas | string get_advertisedValue( | ): string |
vb | function get_advertisedValue( | ) As String |
cs | string get_advertisedValue( | ) |
java | String get_advertisedValue( | ) |
uwp | async Task<string> get_advertisedValue( | ) |
py | get_advertisedValue( | ) |
php | function get_advertisedValue( | ) |
ts | async get_advertisedValue( | ): Promise<string> |
es | async get_advertisedValue( | ) |
dnp | string get_advertisedValue( | ) |
cp | string get_advertisedValue( | ) |
cmd | YAnButton target get_advertisedValue |
Returns :
a string corresponding to the current value of the analog input (no more than 6 characters).
On failure, throws an exception or returns YAnButton.ADVERTISEDVALUE_INVALID.
Tells if a calibration process is currently ongoing.
js | function get_analogCalibration( | ) |
cpp | Y_ANALOGCALIBRATION_enum get_analogCalibration( | ) |
m | -(Y_ANALOGCALIBRATION_enum) analogCalibration |
pas | Integer get_analogCalibration( | ): Integer |
vb | function get_analogCalibration( | ) As Integer |
cs | int get_analogCalibration( | ) |
java | int get_analogCalibration( | ) |
uwp | async Task<int> get_analogCalibration( | ) |
py | get_analogCalibration( | ) |
php | function get_analogCalibration( | ) |
ts | async get_analogCalibration( | ): Promise<YAnButton_AnalogCalibration> |
es | async get_analogCalibration( | ) |
dnp | int get_analogCalibration( | ) |
cp | int get_analogCalibration( | ) |
cmd | YAnButton target get_analogCalibration |
Returns :
either YAnButton.ANALOGCALIBRATION_OFF or YAnButton.ANALOGCALIBRATION_ON
On failure, throws an exception or returns YAnButton.ANALOGCALIBRATION_INVALID.
Returns the current calibrated input value (between 0 and 1000, included).
js | function get_calibratedValue( | ) |
cpp | int get_calibratedValue( | ) |
m | -(int) calibratedValue |
pas | LongInt get_calibratedValue( | ): LongInt |
vb | function get_calibratedValue( | ) As Integer |
cs | int get_calibratedValue( | ) |
java | int get_calibratedValue( | ) |
uwp | async Task<int> get_calibratedValue( | ) |
py | get_calibratedValue( | ) |
php | function get_calibratedValue( | ) |
ts | async get_calibratedValue( | ): Promise<number> |
es | async get_calibratedValue( | ) |
dnp | int get_calibratedValue( | ) |
cp | int get_calibratedValue( | ) |
cmd | YAnButton target get_calibratedValue |
Returns :
an integer corresponding to the current calibrated input value (between 0 and 1000, included)
On failure, throws an exception or returns YAnButton.CALIBRATEDVALUE_INVALID.
Returns the maximal value measured during the calibration (between 0 and 4095, included).
js | function get_calibrationMax( | ) |
cpp | int get_calibrationMax( | ) |
m | -(int) calibrationMax |
pas | LongInt get_calibrationMax( | ): LongInt |
vb | function get_calibrationMax( | ) As Integer |
cs | int get_calibrationMax( | ) |
java | int get_calibrationMax( | ) |
uwp | async Task<int> get_calibrationMax( | ) |
py | get_calibrationMax( | ) |
php | function get_calibrationMax( | ) |
ts | async get_calibrationMax( | ): Promise<number> |
es | async get_calibrationMax( | ) |
dnp | int get_calibrationMax( | ) |
cp | int get_calibrationMax( | ) |
cmd | YAnButton target get_calibrationMax |
Returns :
an integer corresponding to the maximal value measured during the calibration (between 0 and 4095, included)
On failure, throws an exception or returns YAnButton.CALIBRATIONMAX_INVALID.
Returns the minimal value measured during the calibration (between 0 and 4095, included).
js | function get_calibrationMin( | ) |
cpp | int get_calibrationMin( | ) |
m | -(int) calibrationMin |
pas | LongInt get_calibrationMin( | ): LongInt |
vb | function get_calibrationMin( | ) As Integer |
cs | int get_calibrationMin( | ) |
java | int get_calibrationMin( | ) |
uwp | async Task<int> get_calibrationMin( | ) |
py | get_calibrationMin( | ) |
php | function get_calibrationMin( | ) |
ts | async get_calibrationMin( | ): Promise<number> |
es | async get_calibrationMin( | ) |
dnp | int get_calibrationMin( | ) |
cp | int get_calibrationMin( | ) |
cmd | YAnButton target get_calibrationMin |
Returns :
an integer corresponding to the minimal value measured during the calibration (between 0 and 4095, included)
On failure, throws an exception or returns YAnButton.CALIBRATIONMIN_INVALID.
Returns the error message of the latest error with the analog input.
js | function get_errorMessage( | ) |
cpp | string get_errorMessage( | ) |
m | -(NSString*) errorMessage |
pas | string get_errorMessage( | ): string |
vb | function get_errorMessage( | ) As String |
cs | string get_errorMessage( | ) |
java | String get_errorMessage( | ) |
py | get_errorMessage( | ) |
php | function get_errorMessage( | ) |
ts | get_errorMessage( | ): string |
es | get_errorMessage( | ) |
This method is mostly useful when using the Yoctopuce library with exceptions disabled.
Returns :
a string corresponding to the latest error message that occured while using the analog input object
Returns the numerical error code of the latest error with the analog input.
js | function get_errorType( | ) |
cpp | YRETCODE get_errorType( | ) |
m | -(YRETCODE) errorType |
pas | YRETCODE get_errorType( | ): YRETCODE |
vb | function get_errorType( | ) As YRETCODE |
cs | YRETCODE get_errorType( | ) |
java | int get_errorType( | ) |
py | get_errorType( | ) |
php | function get_errorType( | ) |
ts | get_errorType( | ): number |
es | get_errorType( | ) |
This method is mostly useful when using the Yoctopuce library with exceptions disabled.
Returns :
a number corresponding to the code of the latest error that occurred while using the analog input object
Returns a global identifier of the analog input in the format MODULE_NAME.FUNCTION_NAME.
js | function get_friendlyName( | ) |
cpp | string get_friendlyName( | ) |
m | -(NSString*) friendlyName |
cs | string get_friendlyName( | ) |
java | String get_friendlyName( | ) |
py | get_friendlyName( | ) |
php | function get_friendlyName( | ) |
ts | async get_friendlyName( | ): Promise<string> |
es | async get_friendlyName( | ) |
dnp | string get_friendlyName( | ) |
cp | string get_friendlyName( | ) |
The returned string uses the logical names of the module and of the analog input if they are defined, otherwise the serial number of the module and the hardware identifier of the analog input (for example: MyCustomName.relay1)
Returns :
a string that uniquely identifies the analog input using logical names (ex: MyCustomName.relay1)
On failure, throws an exception or returns YAnButton.FRIENDLYNAME_INVALID.
Returns a unique identifier of type YFUN_DESCR corresponding to the function.
js | function get_functionDescriptor( | ) |
cpp | YFUN_DESCR get_functionDescriptor( | ) |
m | -(YFUN_DESCR) functionDescriptor |
pas | YFUN_DESCR get_functionDescriptor( | ): YFUN_DESCR |
vb | function get_functionDescriptor( | ) As YFUN_DESCR |
cs | YFUN_DESCR get_functionDescriptor( | ) |
java | String get_functionDescriptor( | ) |
py | get_functionDescriptor( | ) |
php | function get_functionDescriptor( | ) |
ts | async get_functionDescriptor( | ): Promise<string> |
es | async get_functionDescriptor( | ) |
This identifier can be used to test if two instances of YFunction reference the same physical function on the same physical device.
Returns :
an identifier of type YFUN_DESCR.
If the function has never been contacted, the returned value is Y$CLASSNAME$.FUNCTIONDESCRIPTOR_INVALID.
Returns the hardware identifier of the analog input, without reference to the module.
js | function get_functionId( | ) |
cpp | string get_functionId( | ) |
m | -(NSString*) functionId |
vb | function get_functionId( | ) As String |
cs | string get_functionId( | ) |
java | String get_functionId( | ) |
py | get_functionId( | ) |
php | function get_functionId( | ) |
ts | async get_functionId( | ): Promise<string> |
es | async get_functionId( | ) |
dnp | string get_functionId( | ) |
cp | string get_functionId( | ) |
For example relay1
Returns :
a string that identifies the analog input (ex: relay1)
On failure, throws an exception or returns YAnButton.FUNCTIONID_INVALID.
Returns the unique hardware identifier of the analog input in the form SERIAL.FUNCTIONID.
js | function get_hardwareId( | ) |
cpp | string get_hardwareId( | ) |
m | -(NSString*) hardwareId |
vb | function get_hardwareId( | ) As String |
cs | string get_hardwareId( | ) |
java | String get_hardwareId( | ) |
py | get_hardwareId( | ) |
php | function get_hardwareId( | ) |
ts | async get_hardwareId( | ): Promise<string> |
es | async get_hardwareId( | ) |
dnp | string get_hardwareId( | ) |
cp | string get_hardwareId( | ) |
The unique hardware identifier is composed of the device serial number and of the hardware identifier of the analog input (for example RELAYLO1-123456.relay1).
Returns :
a string that uniquely identifies the analog input (ex: RELAYLO1-123456.relay1)
On failure, throws an exception or returns YAnButton.HARDWAREID_INVALID.
Returns the decoding method applied to the input (analog or multiplexed binary switches).
js | function get_inputType( | ) |
cpp | Y_INPUTTYPE_enum get_inputType( | ) |
m | -(Y_INPUTTYPE_enum) inputType |
pas | Integer get_inputType( | ): Integer |
vb | function get_inputType( | ) As Integer |
cs | int get_inputType( | ) |
java | int get_inputType( | ) |
uwp | async Task<int> get_inputType( | ) |
py | get_inputType( | ) |
php | function get_inputType( | ) |
ts | async get_inputType( | ): Promise<YAnButton_InputType> |
es | async get_inputType( | ) |
dnp | int get_inputType( | ) |
cp | int get_inputType( | ) |
cmd | YAnButton target get_inputType |
Returns :
a value among YAnButton.INPUTTYPE_ANALOG_FAST, YAnButton.INPUTTYPE_DIGITAL4 and YAnButton.INPUTTYPE_ANALOG_SMOOTH corresponding to the decoding method applied to the input (analog or multiplexed binary switches)
On failure, throws an exception or returns YAnButton.INPUTTYPE_INVALID.
Returns true if the input (considered as binary) is active (closed contact), and false otherwise.
js | function get_isPressed( | ) |
cpp | Y_ISPRESSED_enum get_isPressed( | ) |
m | -(Y_ISPRESSED_enum) isPressed |
pas | Integer get_isPressed( | ): Integer |
vb | function get_isPressed( | ) As Integer |
cs | int get_isPressed( | ) |
java | int get_isPressed( | ) |
uwp | async Task<int> get_isPressed( | ) |
py | get_isPressed( | ) |
php | function get_isPressed( | ) |
ts | async get_isPressed( | ): Promise<YAnButton_IsPressed> |
es | async get_isPressed( | ) |
dnp | int get_isPressed( | ) |
cp | int get_isPressed( | ) |
cmd | YAnButton target get_isPressed |
Returns :
either YAnButton.ISPRESSED_FALSE or YAnButton.ISPRESSED_TRUE, according to true if the input (considered as binary) is active (closed contact), and false otherwise
On failure, throws an exception or returns YAnButton.ISPRESSED_INVALID.
Returns the number of elapsed milliseconds between the module power on and the last time the input button was pressed (the input contact transitioned from open to closed).
js | function get_lastTimePressed( | ) |
cpp | s64 get_lastTimePressed( | ) |
m | -(s64) lastTimePressed |
pas | int64 get_lastTimePressed( | ): int64 |
vb | function get_lastTimePressed( | ) As Long |
cs | long get_lastTimePressed( | ) |
java | long get_lastTimePressed( | ) |
uwp | async Task<long> get_lastTimePressed( | ) |
py | get_lastTimePressed( | ) |
php | function get_lastTimePressed( | ) |
ts | async get_lastTimePressed( | ): Promise<number> |
es | async get_lastTimePressed( | ) |
dnp | long get_lastTimePressed( | ) |
cp | s64 get_lastTimePressed( | ) |
cmd | YAnButton target get_lastTimePressed |
Returns :
an integer corresponding to the number of elapsed milliseconds between the module power on and the last time the input button was pressed (the input contact transitioned from open to closed)
On failure, throws an exception or returns YAnButton.LASTTIMEPRESSED_INVALID.
Returns the number of elapsed milliseconds between the module power on and the last time the input button was released (the input contact transitioned from closed to open).
js | function get_lastTimeReleased( | ) |
cpp | s64 get_lastTimeReleased( | ) |
m | -(s64) lastTimeReleased |
pas | int64 get_lastTimeReleased( | ): int64 |
vb | function get_lastTimeReleased( | ) As Long |
cs | long get_lastTimeReleased( | ) |
java | long get_lastTimeReleased( | ) |
uwp | async Task<long> get_lastTimeReleased( | ) |
py | get_lastTimeReleased( | ) |
php | function get_lastTimeReleased( | ) |
ts | async get_lastTimeReleased( | ): Promise<number> |
es | async get_lastTimeReleased( | ) |
dnp | long get_lastTimeReleased( | ) |
cp | s64 get_lastTimeReleased( | ) |
cmd | YAnButton target get_lastTimeReleased |
Returns :
an integer corresponding to the number of elapsed milliseconds between the module power on and the last time the input button was released (the input contact transitioned from closed to open)
On failure, throws an exception or returns YAnButton.LASTTIMERELEASED_INVALID.
Returns the logical name of the analog input.
js | function get_logicalName( | ) |
cpp | string get_logicalName( | ) |
m | -(NSString*) logicalName |
pas | string get_logicalName( | ): string |
vb | function get_logicalName( | ) As String |
cs | string get_logicalName( | ) |
java | String get_logicalName( | ) |
uwp | async Task<string> get_logicalName( | ) |
py | get_logicalName( | ) |
php | function get_logicalName( | ) |
ts | async get_logicalName( | ): Promise<string> |
es | async get_logicalName( | ) |
dnp | string get_logicalName( | ) |
cp | string get_logicalName( | ) |
cmd | YAnButton target get_logicalName |
Returns :
a string corresponding to the logical name of the analog input.
On failure, throws an exception or returns YAnButton.LOGICALNAME_INVALID.
Gets the YModule object for the device on which the function is located.
js | function get_module( | ) |
cpp | YModule * get_module( | ) |
m | -(YModule*) module |
pas | TYModule get_module( | ): TYModule |
vb | function get_module( | ) As YModule |
cs | YModule get_module( | ) |
java | YModule get_module( | ) |
py | get_module( | ) |
php | function get_module( | ) |
ts | async get_module( | ): Promise<YModule> |
es | async get_module( | ) |
dnp | YModuleProxy get_module( | ) |
cp | YModuleProxy * get_module( | ) |
If the function cannot be located on any module, the returned instance of YModule is not shown as on-line.
Returns :
an instance of YModule
Gets the YModule object for the device on which the function is located (asynchronous version).
js | function get_module_async( | callback, context) |
If the function cannot be located on any module, the returned YModule object does not show as on-line.
This asynchronous version exists only in JavaScript. It uses a callback instead of a return value in order to avoid blocking Firefox JavaScript VM that does not implement context switching during blocking I/O calls. See the documentation section on asynchronous JavasSript calls for more details.
Parameters :
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving function object and the requested YModule object |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Returns the pulse counter value.
js | function get_pulseCounter( | ) |
cpp | s64 get_pulseCounter( | ) |
m | -(s64) pulseCounter |
pas | int64 get_pulseCounter( | ): int64 |
vb | function get_pulseCounter( | ) As Long |
cs | long get_pulseCounter( | ) |
java | long get_pulseCounter( | ) |
uwp | async Task<long> get_pulseCounter( | ) |
py | get_pulseCounter( | ) |
php | function get_pulseCounter( | ) |
ts | async get_pulseCounter( | ): Promise<number> |
es | async get_pulseCounter( | ) |
dnp | long get_pulseCounter( | ) |
cp | s64 get_pulseCounter( | ) |
cmd | YAnButton target get_pulseCounter |
The value is a 32 bit integer. In case of overflow (>=2^32), the counter will wrap. To reset the counter, just call the resetCounter() method.
Returns :
an integer corresponding to the pulse counter value
On failure, throws an exception or returns YAnButton.PULSECOUNTER_INVALID.
Returns the timer of the pulses counter (ms).
js | function get_pulseTimer( | ) |
cpp | s64 get_pulseTimer( | ) |
m | -(s64) pulseTimer |
pas | int64 get_pulseTimer( | ): int64 |
vb | function get_pulseTimer( | ) As Long |
cs | long get_pulseTimer( | ) |
java | long get_pulseTimer( | ) |
uwp | async Task<long> get_pulseTimer( | ) |
py | get_pulseTimer( | ) |
php | function get_pulseTimer( | ) |
ts | async get_pulseTimer( | ): Promise<number> |
es | async get_pulseTimer( | ) |
dnp | long get_pulseTimer( | ) |
cp | s64 get_pulseTimer( | ) |
cmd | YAnButton target get_pulseTimer |
Returns :
an integer corresponding to the timer of the pulses counter (ms)
On failure, throws an exception or returns YAnButton.PULSETIMER_INVALID.
Returns the current measured input value as-is (between 0 and 4095, included).
js | function get_rawValue( | ) |
cpp | int get_rawValue( | ) |
m | -(int) rawValue |
pas | LongInt get_rawValue( | ): LongInt |
vb | function get_rawValue( | ) As Integer |
cs | int get_rawValue( | ) |
java | int get_rawValue( | ) |
uwp | async Task<int> get_rawValue( | ) |
py | get_rawValue( | ) |
php | function get_rawValue( | ) |
ts | async get_rawValue( | ): Promise<number> |
es | async get_rawValue( | ) |
dnp | int get_rawValue( | ) |
cp | int get_rawValue( | ) |
cmd | YAnButton target get_rawValue |
Returns :
an integer corresponding to the current measured input value as-is (between 0 and 4095, included)
On failure, throws an exception or returns YAnButton.RAWVALUE_INVALID.
Returns the sensibility for the input (between 1 and 1000) for triggering user callbacks.
js | function get_sensitivity( | ) |
cpp | int get_sensitivity( | ) |
m | -(int) sensitivity |
pas | LongInt get_sensitivity( | ): LongInt |
vb | function get_sensitivity( | ) As Integer |
cs | int get_sensitivity( | ) |
java | int get_sensitivity( | ) |
uwp | async Task<int> get_sensitivity( | ) |
py | get_sensitivity( | ) |
php | function get_sensitivity( | ) |
ts | async get_sensitivity( | ): Promise<number> |
es | async get_sensitivity( | ) |
dnp | int get_sensitivity( | ) |
cp | int get_sensitivity( | ) |
cmd | YAnButton target get_sensitivity |
Returns :
an integer corresponding to the sensibility for the input (between 1 and 1000) for triggering user callbacks
On failure, throws an exception or returns YAnButton.SENSITIVITY_INVALID.
Returns the serial number of the module, as set by the factory.
js | function get_serialNumber( | ) |
cpp | string get_serialNumber( | ) |
m | -(NSString*) serialNumber |
pas | string get_serialNumber( | ): string |
vb | function get_serialNumber( | ) As String |
cs | string get_serialNumber( | ) |
java | String get_serialNumber( | ) |
uwp | async Task<string> get_serialNumber( | ) |
py | get_serialNumber( | ) |
php | function get_serialNumber( | ) |
ts | async get_serialNumber( | ): Promise<string> |
es | async get_serialNumber( | ) |
dnp | string get_serialNumber( | ) |
cp | string get_serialNumber( | ) |
cmd | YAnButton target get_serialNumber |
Returns :
a string corresponding to the serial number of the module, as set by the factory.
On failure, throws an exception or returns YFunction.SERIALNUMBER_INVALID.
Returns the value of the userData attribute, as previously stored using method set_userData.
js | function get_userData( | ) |
cpp | void * get_userData( | ) |
m | -(id) userData |
pas | Tobject get_userData( | ): Tobject |
vb | function get_userData( | ) As Object |
cs | object get_userData( | ) |
java | Object get_userData( | ) |
py | get_userData( | ) |
php | function get_userData( | ) |
ts | async get_userData( | ): Promise<object|null> |
es | async get_userData( | ) |
This attribute is never touched directly by the API, and is at disposal of the caller to store a context.
Returns :
the object stored previously by the caller.
Checks if the analog input is currently reachable, without raising any error.
js | function isOnline( | ) |
cpp | bool isOnline( | ) |
m | -(BOOL) isOnline |
pas | boolean isOnline( | ): boolean |
vb | function isOnline( | ) As Boolean |
cs | bool isOnline( | ) |
java | boolean isOnline( | ) |
py | isOnline( | ) |
php | function isOnline( | ) |
ts | async isOnline( | ): Promise<boolean> |
es | async isOnline( | ) |
dnp | bool isOnline( | ) |
cp | bool isOnline( | ) |
If there is a cached value for the analog input in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the analog input.
Returns :
true if the analog input can be reached, and false otherwise
Checks if the analog input is currently reachable, without raising any error (asynchronous version).
js | function isOnline_async( | callback, context) |
If there is a cached value for the analog input in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the requested function.
This asynchronous version exists only in Javascript. It uses a callback instead of a return value in order to avoid blocking the Javascript virtual machine.
Parameters :
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving function object and the boolean result |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Test if the function is readOnly.
cpp | bool isReadOnly( | ) |
m | -(bool) isReadOnly |
pas | boolean isReadOnly( | ): boolean |
vb | function isReadOnly( | ) As Boolean |
cs | bool isReadOnly( | ) |
java | boolean isReadOnly( | ) |
uwp | async Task<bool> isReadOnly( | ) |
py | isReadOnly( | ) |
php | function isReadOnly( | ) |
ts | async isReadOnly( | ): Promise<boolean> |
es | async isReadOnly( | ) |
dnp | bool isReadOnly( | ) |
cp | bool isReadOnly( | ) |
cmd | YAnButton target isReadOnly |
Return true if the function is write protected or that the function is not available.
Returns :
true if the function is readOnly or not online.
Preloads the analog input cache with a specified validity duration.
js | function load( | msValidity) |
cpp | YRETCODE load( | int msValidity) |
m | -(YRETCODE) load | : (u64) msValidity |
pas | YRETCODE load( | msValidity: u64): YRETCODE |
vb | function load( | ByVal msValidity As Long) As YRETCODE |
cs | YRETCODE load( | ulong msValidity) |
java | int load( | long msValidity) |
py | load( | msValidity) |
php | function load( | $msValidity) |
ts | async load( | msValidity: number): Promise<number> |
es | async load( | msValidity) |
By default, whenever accessing a device, all function attributes are kept in cache for the standard duration (5 ms). This method can be used to temporarily mark the cache as valid for a longer period, in order to reduce network traffic for instance.
Parameters :
msValidity | an integer corresponding to the validity attributed to the loaded function parameters, in milliseconds |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Returns the current value of a single function attribute, as a text string, as quickly as possible but without using the cached value.
js | function loadAttribute( | attrName) |
cpp | string loadAttribute( | string attrName) |
m | -(NSString*) loadAttribute | : (NSString*) attrName |
pas | string loadAttribute( | attrName: string): string |
vb | function loadAttribute( | ByVal attrName As String) As String |
cs | string loadAttribute( | string attrName) |
java | String loadAttribute( | String attrName) |
uwp | async Task<string> loadAttribute( | string attrName) |
py | loadAttribute( | attrName) |
php | function loadAttribute( | $attrName) |
ts | async loadAttribute( | attrName: string): Promise<string> |
es | async loadAttribute( | attrName) |
dnp | string loadAttribute( | string attrName) |
cp | string loadAttribute( | string attrName) |
Parameters :
attrName | the name of the requested attribute |
Returns :
a string with the value of the the attribute
On failure, throws an exception or returns an empty string.
Preloads the analog input cache with a specified validity duration (asynchronous version).
js | function load_async( | msValidity, callback, context) |
By default, whenever accessing a device, all function attributes are kept in cache for the standard duration (5 ms). This method can be used to temporarily mark the cache as valid for a longer period, in order to reduce network traffic for instance.
This asynchronous version exists only in JavaScript. It uses a callback instead of a return value in order to avoid blocking the JavaScript virtual machine.
Parameters :
msValidity | an integer corresponding to the validity of the loaded function parameters, in milliseconds |
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving function object and the error code (or YAPI.SUCCESS) |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Disables the propagation of every new advertised value to the parent hub.
js | function muteValueCallbacks( | ) |
cpp | int muteValueCallbacks( | ) |
m | -(int) muteValueCallbacks |
pas | LongInt muteValueCallbacks( | ): LongInt |
vb | function muteValueCallbacks( | ) As Integer |
cs | int muteValueCallbacks( | ) |
java | int muteValueCallbacks( | ) |
uwp | async Task<int> muteValueCallbacks( | ) |
py | muteValueCallbacks( | ) |
php | function muteValueCallbacks( | ) |
ts | async muteValueCallbacks( | ): Promise<number> |
es | async muteValueCallbacks( | ) |
dnp | int muteValueCallbacks( | ) |
cp | int muteValueCallbacks( | ) |
cmd | YAnButton target muteValueCallbacks |
You can use this function to save bandwidth and CPU on computers with limited resources, or to prevent unwanted invocations of the HTTP callback. Remember to call the saveToFlash() method of the module if the modification must be kept.
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Continues the enumeration of analog inputs started using yFirstAnButton().
js | function nextAnButton( | ) |
cpp | YAnButton * nextAnButton( | ) |
m | -(nullable YAnButton*) nextAnButton |
pas | TYAnButton nextAnButton( | ): TYAnButton |
vb | function nextAnButton( | ) As YAnButton |
cs | YAnButton nextAnButton( | ) |
java | YAnButton nextAnButton( | ) |
uwp | YAnButton nextAnButton( | ) |
py | nextAnButton( | ) |
php | function nextAnButton( | ) |
ts | nextAnButton( | ): YAnButton | null |
es | nextAnButton( | ) |
Caution: You can't make any assumption about the returned analog inputs order. If you want to find a specific an analog input, use AnButton.findAnButton() and a hardwareID or a logical name.
Returns :
a pointer to a YAnButton object, corresponding to an analog input currently online, or a null pointer if there are no more analog inputs to enumerate.
Registers the callback function that is invoked on every change of advertised value.
js | function registerValueCallback( | callback) |
cpp | int registerValueCallback( | YAnButtonValueCallback callback) |
m | -(int) registerValueCallback | : (YAnButtonValueCallback _Nullable) callback |
pas | LongInt registerValueCallback( | callback: TYAnButtonValueCallback): LongInt |
vb | function registerValueCallback( | ByVal callback As YAnButtonValueCallback) As Integer |
cs | int registerValueCallback( | ValueCallback callback) |
java | int registerValueCallback( | UpdateCallback callback) |
uwp | async Task<int> registerValueCallback( | ValueCallback callback) |
py | registerValueCallback( | callback) |
php | function registerValueCallback( | $callback) |
ts | async registerValueCallback( | callback: YAnButtonValueCallback | null): Promise<number> |
es | async registerValueCallback( | callback) |
The callback is invoked only during the execution of ySleep or yHandleEvents. This provides control over the time when the callback is triggered. For good responsiveness, remember to call one of these two functions periodically. To unregister a callback, pass a null pointer as argument.
Parameters :
callback | the callback function to call, or a null pointer. The callback function should take two arguments: the function object of which the value has changed, and the character string describing the new advertised value. |
Returns the pulse counter value as well as its timer.
js | function resetCounter( | ) |
cpp | int resetCounter( | ) |
m | -(int) resetCounter |
pas | LongInt resetCounter( | ): LongInt |
vb | function resetCounter( | ) As Integer |
cs | int resetCounter( | ) |
java | int resetCounter( | ) |
uwp | async Task<int> resetCounter( | ) |
py | resetCounter( | ) |
php | function resetCounter( | ) |
ts | async resetCounter( | ): Promise<number> |
es | async resetCounter( | ) |
dnp | int resetCounter( | ) |
cp | int resetCounter( | ) |
cmd | YAnButton target resetCounter |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Starts or stops the calibration process.
js | function set_analogCalibration( | newval) |
cpp | int set_analogCalibration( | Y_ANALOGCALIBRATION_enum newval) |
m | -(int) setAnalogCalibration | : (Y_ANALOGCALIBRATION_enum) newval |
pas | integer set_analogCalibration( | newval: Integer): integer |
vb | function set_analogCalibration( | ByVal newval As Integer) As Integer |
cs | int set_analogCalibration( | int newval) |
java | int set_analogCalibration( | int newval) |
uwp | async Task<int> set_analogCalibration( | int newval) |
py | set_analogCalibration( | newval) |
php | function set_analogCalibration( | $newval) |
ts | async set_analogCalibration( | newval: YAnButton_AnalogCalibration): Promise<number> |
es | async set_analogCalibration( | newval) |
dnp | int set_analogCalibration( | int newval) |
cp | int set_analogCalibration( | int newval) |
cmd | YAnButton target set_analogCalibration | newval |
Remember to call the saveToFlash() method of the module at the end of the calibration if the modification must be kept.
Parameters :
newval | either YAnButton.ANALOGCALIBRATION_OFF or YAnButton.ANALOGCALIBRATION_ON |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the maximal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration.
js | function set_calibrationMax( | newval) |
cpp | int set_calibrationMax( | int newval) |
m | -(int) setCalibrationMax | : (int) newval |
pas | integer set_calibrationMax( | newval: LongInt): integer |
vb | function set_calibrationMax( | ByVal newval As Integer) As Integer |
cs | int set_calibrationMax( | int newval) |
java | int set_calibrationMax( | int newval) |
uwp | async Task<int> set_calibrationMax( | int newval) |
py | set_calibrationMax( | newval) |
php | function set_calibrationMax( | $newval) |
ts | async set_calibrationMax( | newval: number): Promise<number> |
es | async set_calibrationMax( | newval) |
dnp | int set_calibrationMax( | int newval) |
cp | int set_calibrationMax( | int newval) |
cmd | YAnButton target set_calibrationMax | newval |
Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | an integer corresponding to the maximal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the minimal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration.
js | function set_calibrationMin( | newval) |
cpp | int set_calibrationMin( | int newval) |
m | -(int) setCalibrationMin | : (int) newval |
pas | integer set_calibrationMin( | newval: LongInt): integer |
vb | function set_calibrationMin( | ByVal newval As Integer) As Integer |
cs | int set_calibrationMin( | int newval) |
java | int set_calibrationMin( | int newval) |
uwp | async Task<int> set_calibrationMin( | int newval) |
py | set_calibrationMin( | newval) |
php | function set_calibrationMin( | $newval) |
ts | async set_calibrationMin( | newval: number): Promise<number> |
es | async set_calibrationMin( | newval) |
dnp | int set_calibrationMin( | int newval) |
cp | int set_calibrationMin( | int newval) |
cmd | YAnButton target set_calibrationMin | newval |
Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | an integer corresponding to the minimal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the decoding method applied to the input (analog or multiplexed binary switches).
js | function set_inputType( | newval) |
cpp | int set_inputType( | Y_INPUTTYPE_enum newval) |
m | -(int) setInputType | : (Y_INPUTTYPE_enum) newval |
pas | integer set_inputType( | newval: Integer): integer |
vb | function set_inputType( | ByVal newval As Integer) As Integer |
cs | int set_inputType( | int newval) |
java | int set_inputType( | int newval) |
uwp | async Task<int> set_inputType( | int newval) |
py | set_inputType( | newval) |
php | function set_inputType( | $newval) |
ts | async set_inputType( | newval: YAnButton_InputType): Promise<number> |
es | async set_inputType( | newval) |
dnp | int set_inputType( | int newval) |
cp | int set_inputType( | int newval) |
cmd | YAnButton target set_inputType | newval |
Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | a value among YAnButton.INPUTTYPE_ANALOG_FAST, YAnButton.INPUTTYPE_DIGITAL4 and YAnButton.INPUTTYPE_ANALOG_SMOOTH corresponding to the decoding method applied to the input (analog or multiplexed binary switches) |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the logical name of the analog input.
js | function set_logicalName( | newval) |
cpp | int set_logicalName( | string newval) |
m | -(int) setLogicalName | : (NSString*) newval |
pas | integer set_logicalName( | newval: string): integer |
vb | function set_logicalName( | ByVal newval As String) As Integer |
cs | int set_logicalName( | string newval) |
java | int set_logicalName( | String newval) |
uwp | async Task<int> set_logicalName( | string newval) |
py | set_logicalName( | newval) |
php | function set_logicalName( | $newval) |
ts | async set_logicalName( | newval: string): Promise<number> |
es | async set_logicalName( | newval) |
dnp | int set_logicalName( | string newval) |
cp | int set_logicalName( | string newval) |
cmd | YAnButton target set_logicalName | newval |
You can use yCheckLogicalName() prior to this call to make sure that your parameter is valid. Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | a string corresponding to the logical name of the analog input. |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the sensibility for the input (between 1 and 1000) for triggering user callbacks.
js | function set_sensitivity( | newval) |
cpp | int set_sensitivity( | int newval) |
m | -(int) setSensitivity | : (int) newval |
pas | integer set_sensitivity( | newval: LongInt): integer |
vb | function set_sensitivity( | ByVal newval As Integer) As Integer |
cs | int set_sensitivity( | int newval) |
java | int set_sensitivity( | int newval) |
uwp | async Task<int> set_sensitivity( | int newval) |
py | set_sensitivity( | newval) |
php | function set_sensitivity( | $newval) |
ts | async set_sensitivity( | newval: number): Promise<number> |
es | async set_sensitivity( | newval) |
dnp | int set_sensitivity( | int newval) |
cp | int set_sensitivity( | int newval) |
cmd | YAnButton target set_sensitivity | newval |
The sensibility is used to filter variations around a fixed value, but does not preclude the transmission of events when the input value evolves constantly in the same direction. Special case: when the value 1000 is used, the callback will only be thrown when the logical state of the input switches from pressed to released and back. Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | an integer corresponding to the sensibility for the input (between 1 and 1000) for triggering user callbacks |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Stores a user context provided as argument in the userData attribute of the function.
js | function set_userData( | data) |
cpp | void set_userData( | void * data) |
m | -(void) setUserData | : (id) data |
pas | set_userData( | data: Tobject) |
vb | procedure set_userData( | ByVal data As Object) |
cs | void set_userData( | object data) |
java | void set_userData( | Object data) |
py | set_userData( | data) |
php | function set_userData( | $data) |
ts | async set_userData( | data: object|null): Promise<void> |
es | async set_userData( | data) |
This attribute is never touched by the API, and is at disposal of the caller to store a context.
Parameters :
data | any kind of object to be stored |
Re-enables the propagation of every new advertised value to the parent hub.
js | function unmuteValueCallbacks( | ) |
cpp | int unmuteValueCallbacks( | ) |
m | -(int) unmuteValueCallbacks |
pas | LongInt unmuteValueCallbacks( | ): LongInt |
vb | function unmuteValueCallbacks( | ) As Integer |
cs | int unmuteValueCallbacks( | ) |
java | int unmuteValueCallbacks( | ) |
uwp | async Task<int> unmuteValueCallbacks( | ) |
py | unmuteValueCallbacks( | ) |
php | function unmuteValueCallbacks( | ) |
ts | async unmuteValueCallbacks( | ): Promise<number> |
es | async unmuteValueCallbacks( | ) |
dnp | int unmuteValueCallbacks( | ) |
cp | int unmuteValueCallbacks( | ) |
cmd | YAnButton target unmuteValueCallbacks |
This function reverts the effect of a previous call to muteValueCallbacks(). Remember to call the saveToFlash() method of the module if the modification must be kept.
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Waits for all pending asynchronous commands on the module to complete, and invoke the user-provided callback function.
js | function wait_async( | callback, context) |
ts | wait_async( | callback: Function, context: object) |
es | wait_async( | callback, context) |
The callback function can therefore freely issue synchronous or asynchronous commands, without risking to block the JavaScript VM.
Parameters :
callback | callback function that is invoked when all pending commands on the module are completed. The callback function receives two arguments: the caller-specific context object and the receiving function object. |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing.
Buzzer control interface, available for instance in the Yocto-Buzzer or the Yocto-MaxiBuzzer
The YBuzzer class allows you to drive a buzzer. You can choose the frequency and the volume at which the buzzer must sound. You can also pre-program a play sequence.
In order to use the functions described here, you should include:
es | in HTML: <script src="../../lib/yocto_buzzer.js"></script> in node.js: require('yoctolib-es2017/yocto_buzzer.js'); |
js | <script type='text/javascript' src='yocto_buzzer.js'></script> |
cpp | #include "yocto_buzzer.h" |
m | #import "yocto_buzzer.h" |
pas | uses yocto_buzzer; |
vb | yocto_buzzer.vb |
cs | yocto_buzzer.cs |
java | import com.yoctopuce.YoctoAPI.YBuzzer; |
uwp | import com.yoctopuce.YoctoAPI.YBuzzer; |
py | from yocto_buzzer import * |
php | require_once('yocto_buzzer.php'); |
ts | in HTML: import { YBuzzer } from '../../dist/esm/yocto_buzzer.js'; in Node.js: import { YBuzzer } from 'yoctolib-cjs/yocto_buzzer.js'; |
dnp | import YoctoProxyAPI.YBuzzerProxy |
cp | #include "yocto_buzzer_proxy.h" |
vi | YBuzzer.vi |
ml | import YoctoProxyAPI.YBuzzerProxy |
Global functions |
---|
YBuzzer.FindBuzzer(func) |
Retrieves a buzzer for a given identifier. |
YBuzzer.FindBuzzerInContext(yctx, func) |
Retrieves a buzzer for a given identifier in a YAPI context. |
YBuzzer.FirstBuzzer() |
Starts the enumeration of buzzers currently accessible. |
YBuzzer.FirstBuzzerInContext(yctx) |
Starts the enumeration of buzzers currently accessible. |
YBuzzer.GetSimilarFunctions() |
Enumerates all functions of type Buzzer available on the devices currently reachable by the library, and returns their unique hardware ID. |
YBuzzer properties |
buzzer→AdvertisedValue [read-only] |
Short string representing the current state of the function. |
buzzer→Frequency [writable] |
Frequency of the signal sent to the buzzer/speaker. |
buzzer→FriendlyName [read-only] |
Global identifier of the function in the format MODULE_NAME.FUNCTION_NAME. |
buzzer→FunctionId [read-only] |
Hardware identifier of the buzzer, without reference to the module. |
buzzer→HardwareId [read-only] |
Unique hardware identifier of the function in the form SERIAL.FUNCTIONID. |
buzzer→IsOnline [read-only] |
Checks if the function is currently reachable. |
buzzer→LogicalName [writable] |
Logical name of the function. |
buzzer→PlaySeqMaxSize [read-only] |
Maximum length of the playing sequence. |
buzzer→SerialNumber [read-only] |
Serial number of the module, as set by the factory. |
buzzer→Volume [writable] |
Volume of the signal sent to the buzzer/speaker. |
YBuzzer methods |
buzzer→addFreqMoveToPlaySeq(freq, msDelay) |
Adds a new frequency transition to the playing sequence. |
buzzer→addNotesToPlaySeq(notes) |
Adds notes to the playing sequence. |
buzzer→addPulseToPlaySeq(freq, msDuration) |
Adds a pulse to the playing sequence. |
buzzer→addVolMoveToPlaySeq(volume, msDuration) |
Adds a new volume transition to the playing sequence. |
buzzer→clearCache() |
Invalidates the cache. |
buzzer→describe() |
Returns a short text that describes unambiguously the instance of the buzzer in the form TYPE(NAME)=SERIAL.FUNCTIONID. |
buzzer→freqMove(frequency, duration) |
Makes the buzzer frequency change over a period of time. |
buzzer→get_advertisedValue() |
Returns the current value of the buzzer (no more than 6 characters). |
buzzer→get_errorMessage() |
Returns the error message of the latest error with the buzzer. |
buzzer→get_errorType() |
Returns the numerical error code of the latest error with the buzzer. |
buzzer→get_frequency() |
Returns the frequency of the signal sent to the buzzer/speaker. |
buzzer→get_friendlyName() |
Returns a global identifier of the buzzer in the format MODULE_NAME.FUNCTION_NAME. |
buzzer→get_functionDescriptor() |
Returns a unique identifier of type YFUN_DESCR corresponding to the function. |
buzzer→get_functionId() |
Returns the hardware identifier of the buzzer, without reference to the module. |
buzzer→get_hardwareId() |
Returns the unique hardware identifier of the buzzer in the form SERIAL.FUNCTIONID. |
buzzer→get_logicalName() |
Returns the logical name of the buzzer. |
buzzer→get_module() |
Gets the YModule object for the device on which the function is located. |
buzzer→get_module_async(callback, context) |
Gets the YModule object for the device on which the function is located (asynchronous version). |
buzzer→get_playSeqMaxSize() |
Returns the maximum length of the playing sequence. |
buzzer→get_playSeqSignature() |
Returns the playing sequence signature. |
buzzer→get_playSeqSize() |
Returns the current length of the playing sequence. |
buzzer→get_serialNumber() |
Returns the serial number of the module, as set by the factory. |
buzzer→get_userData() |
Returns the value of the userData attribute, as previously stored using method set_userData. |
buzzer→get_volume() |
Returns the volume of the signal sent to the buzzer/speaker. |
buzzer→isOnline() |
Checks if the buzzer is currently reachable, without raising any error. |
buzzer→isOnline_async(callback, context) |
Checks if the buzzer is currently reachable, without raising any error (asynchronous version). |
buzzer→isReadOnly() |
Test if the function is readOnly. |
buzzer→load(msValidity) |
Preloads the buzzer cache with a specified validity duration. |
buzzer→loadAttribute(attrName) |
Returns the current value of a single function attribute, as a text string, as quickly as possible but without using the cached value. |
buzzer→load_async(msValidity, callback, context) |
Preloads the buzzer cache with a specified validity duration (asynchronous version). |
buzzer→muteValueCallbacks() |
Disables the propagation of every new advertised value to the parent hub. |
buzzer→nextBuzzer() |
Continues the enumeration of buzzers started using yFirstBuzzer(). |
buzzer→oncePlaySeq() |
Starts the preprogrammed playing sequence and run it once only. |
buzzer→playNotes(notes) |
Immediately play a note sequence. |
buzzer→pulse(frequency, duration) |
Activates the buzzer for a short duration. |
buzzer→registerValueCallback(callback) |
Registers the callback function that is invoked on every change of advertised value. |
buzzer→reloadPlaySeq() |
Reloads the preprogrammed playing sequence from the flash memory. |
buzzer→resetPlaySeq() |
Resets the preprogrammed playing sequence and sets the frequency to zero. |
buzzer→savePlaySeq() |
Saves the preprogrammed playing sequence to flash memory. |
buzzer→set_frequency(newval) |
Changes the frequency of the signal sent to the buzzer. |
buzzer→set_logicalName(newval) |
Changes the logical name of the buzzer. |
buzzer→set_userData(data) |
Stores a user context provided as argument in the userData attribute of the function. |
buzzer→set_volume(newval) |
Changes the volume of the signal sent to the buzzer/speaker. |
buzzer→startPlaySeq() |
Starts the preprogrammed playing sequence. |
buzzer→stopPlaySeq() |
Stops the preprogrammed playing sequence and sets the frequency to zero. |
buzzer→unmuteValueCallbacks() |
Re-enables the propagation of every new advertised value to the parent hub. |
buzzer→volumeMove(volume, duration) |
Makes the buzzer volume change over a period of time, frequency stays untouched. |
buzzer→wait_async(callback, context) |
Waits for all pending asynchronous commands on the module to complete, and invoke the user-provided callback function. |
Retrieves a buzzer for a given identifier.
js | function yFindBuzzer( | func) |
cpp | YBuzzer* FindBuzzer( | string func) |
m | +(YBuzzer*) FindBuzzer | : (NSString*) func |
pas | TYBuzzer yFindBuzzer( | func: string): TYBuzzer |
vb | function FindBuzzer( | ByVal func As String) As YBuzzer |
cs | static YBuzzer FindBuzzer( | string func) |
java | static YBuzzer FindBuzzer( | String func) |
uwp | static YBuzzer FindBuzzer( | string func) |
py | FindBuzzer( | func) |
php | function FindBuzzer( | $func) |
ts | static FindBuzzer( | func: string): YBuzzer |
es | static FindBuzzer( | func) |
dnp | static YBuzzerProxy FindBuzzer( | string func) |
cp | static YBuzzerProxy * FindBuzzer( | string func) |
The identifier can be specified using several formats:
This function does not require that the buzzer is online at the time it is invoked. The returned object is nevertheless valid. Use the method YBuzzer.isOnline() to test if the buzzer is indeed online at a given time. In case of ambiguity when looking for a buzzer by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.
If a call to this object's is_online() method returns FALSE although you are certain that the matching device is plugged, make sure that you did call registerHub() at application initialization time.
Parameters :
func | a string that uniquely characterizes the buzzer, for instance YBUZZER2.buzzer. |
Returns :
a YBuzzer object allowing you to drive the buzzer.
Retrieves a buzzer for a given identifier in a YAPI context.
java | static YBuzzer FindBuzzerInContext( | YAPIContext yctx, String func) |
uwp | static YBuzzer FindBuzzerInContext( | YAPIContext yctx, string func) |
ts | static FindBuzzerInContext( | yctx: YAPIContext, func: string): YBuzzer |
es | static FindBuzzerInContext( | yctx, func) |
The identifier can be specified using several formats:
This function does not require that the buzzer is online at the time it is invoked. The returned object is nevertheless valid. Use the method YBuzzer.isOnline() to test if the buzzer is indeed online at a given time. In case of ambiguity when looking for a buzzer by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.
Parameters :
yctx | a YAPI context |
func | a string that uniquely characterizes the buzzer, for instance YBUZZER2.buzzer. |
Returns :
a YBuzzer object allowing you to drive the buzzer.
Starts the enumeration of buzzers currently accessible.
js | function yFirstBuzzer( | ) |
cpp | YBuzzer * FirstBuzzer( | ) |
m | +(YBuzzer*) FirstBuzzer |
pas | TYBuzzer yFirstBuzzer( | ): TYBuzzer |
vb | function FirstBuzzer( | ) As YBuzzer |
cs | static YBuzzer FirstBuzzer( | ) |
java | static YBuzzer FirstBuzzer( | ) |
uwp | static YBuzzer FirstBuzzer( | ) |
py | FirstBuzzer( | ) |
php | function FirstBuzzer( | ) |
ts | static FirstBuzzer( | ): YBuzzer | null |
es | static FirstBuzzer( | ) |
Use the method YBuzzer.nextBuzzer() to iterate on next buzzers.
Returns :
a pointer to a YBuzzer object, corresponding to the first buzzer currently online, or a null pointer if there are none.
Starts the enumeration of buzzers currently accessible.
java | static YBuzzer FirstBuzzerInContext( | YAPIContext yctx) |
uwp | static YBuzzer FirstBuzzerInContext( | YAPIContext yctx) |
ts | static FirstBuzzerInContext( | yctx: YAPIContext): YBuzzer | null |
es | static FirstBuzzerInContext( | yctx) |
Use the method YBuzzer.nextBuzzer() to iterate on next buzzers.
Parameters :
yctx | a YAPI context. |
Returns :
a pointer to a YBuzzer object, corresponding to the first buzzer currently online, or a null pointer if there are none.
Enumerates all functions of type Buzzer available on the devices currently reachable by the library, and returns their unique hardware ID.
dnp | static new string[] GetSimilarFunctions( | ) |
cp | static vector<string> GetSimilarFunctions( | ) |
Each of these IDs can be provided as argument to the method YBuzzer.FindBuzzer to obtain an object that can control the corresponding device.
Returns :
an array of strings, each string containing the unique hardwareId of a device function currently connected.
Short string representing the current state of the function.
dnp | string AdvertisedValue |
Frequency of the signal sent to the buzzer/speaker.
dnp | double Frequency |
Writable. Changes the frequency of the signal sent to the buzzer. A zero value stops the buzzer.
Global identifier of the function in the format MODULE_NAME.FUNCTION_NAME.
dnp | string FriendlyName |
The returned string uses the logical names of the module and of the function if they are defined, otherwise the serial number of the module and the hardware identifier of the function (for example: MyCustomName.relay1)
Hardware identifier of the buzzer, without reference to the module.
dnp | string FunctionId |
For example relay1
Unique hardware identifier of the function in the form SERIAL.FUNCTIONID.
dnp | string HardwareId |
The unique hardware identifier is composed of the device serial number and of the hardware identifier of the function (for example RELAYLO1-123456.relay1).
Checks if the function is currently reachable.
dnp | bool IsOnline |
If there is a cached value for the function in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the function.
Logical name of the function.
dnp | string LogicalName |
Writable. You can use yCheckLogicalName() prior to this call to make sure that your parameter is valid. Remember to call the saveToFlash() method of the module if the modification must be kept.
Maximum length of the playing sequence.
dnp | int PlaySeqMaxSize |
Serial number of the module, as set by the factory.
dnp | string SerialNumber |
Volume of the signal sent to the buzzer/speaker.
dnp | int Volume |
Writable. Remember to call the saveToFlash() method of the module if the modification must be kept.
Adds a new frequency transition to the playing sequence.
js | function addFreqMoveToPlaySeq( | freq, msDelay) |
cpp | int addFreqMoveToPlaySeq( | int freq, int msDelay) |
m | -(int) addFreqMoveToPlaySeq | : (int) freq |
: (int) msDelay |
pas | LongInt addFreqMoveToPlaySeq( | freq: LongInt, msDelay: LongInt): LongInt |
vb | function addFreqMoveToPlaySeq( | ByVal freq As Integer, |
ByVal msDelay As Integer) As Integer |
cs | int addFreqMoveToPlaySeq( | int freq, int msDelay) |
java | int addFreqMoveToPlaySeq( | int freq, int msDelay) |
uwp | async Task<int> addFreqMoveToPlaySeq( | int freq, int msDelay) |
py | addFreqMoveToPlaySeq( | freq, msDelay) |
php | function addFreqMoveToPlaySeq( | $freq, $msDelay) |
ts | async addFreqMoveToPlaySeq( | freq: number, msDelay: number): Promise<number> |
es | async addFreqMoveToPlaySeq( | freq, msDelay) |
dnp | int addFreqMoveToPlaySeq( | int freq, int msDelay) |
cp | int addFreqMoveToPlaySeq( | int freq, int msDelay) |
cmd | YBuzzer target addFreqMoveToPlaySeq | freq msDelay |
Parameters :
freq | desired frequency when the transition is completed, in Hz |
msDelay | duration of the frequency transition, in milliseconds. |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Adds notes to the playing sequence.
js | function addNotesToPlaySeq( | notes) |
cpp | int addNotesToPlaySeq( | string notes) |
m | -(int) addNotesToPlaySeq | : (NSString*) notes |
pas | LongInt addNotesToPlaySeq( | notes: string): LongInt |
vb | function addNotesToPlaySeq( | ByVal notes As String) As Integer |
cs | int addNotesToPlaySeq( | string notes) |
java | int addNotesToPlaySeq( | String notes) |
uwp | async Task<int> addNotesToPlaySeq( | string notes) |
py | addNotesToPlaySeq( | notes) |
php | function addNotesToPlaySeq( | $notes) |
ts | async addNotesToPlaySeq( | notes: string): Promise<number> |
es | async addNotesToPlaySeq( | notes) |
dnp | int addNotesToPlaySeq( | string notes) |
cp | int addNotesToPlaySeq( | string notes) |
cmd | YBuzzer target addNotesToPlaySeq | notes |
Notes are provided as text words, separated by spaces. The pitch is specified using the usual letter from A to G. The duration is specified as the divisor of a whole note: 4 for a fourth, 8 for an eight note, etc. Some modifiers are supported: # and b to alter a note pitch, ' and , to move to the upper/lower octave, . to enlarge the note duration.
Parameters :
notes | notes to be played, as a text string. |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Adds a pulse to the playing sequence.
js | function addPulseToPlaySeq( | freq, msDuration) |
cpp | int addPulseToPlaySeq( | int freq, int msDuration) |
m | -(int) addPulseToPlaySeq | : (int) freq |
: (int) msDuration |
pas | LongInt addPulseToPlaySeq( | freq: LongInt, msDuration: LongInt): LongInt |
vb | function addPulseToPlaySeq( | ByVal freq As Integer, |
ByVal msDuration As Integer) As Integer |
cs | int addPulseToPlaySeq( | int freq, int msDuration) |
java | int addPulseToPlaySeq( | int freq, int msDuration) |
uwp | async Task<int> addPulseToPlaySeq( | int freq, int msDuration) |
py | addPulseToPlaySeq( | freq, msDuration) |
php | function addPulseToPlaySeq( | $freq, $msDuration) |
ts | async addPulseToPlaySeq( | freq: number, msDuration: number): Promise<number> |
es | async addPulseToPlaySeq( | freq, msDuration) |
dnp | int addPulseToPlaySeq( | int freq, int msDuration) |
cp | int addPulseToPlaySeq( | int freq, int msDuration) |
cmd | YBuzzer target addPulseToPlaySeq | freq msDuration |
Parameters :
freq | pulse frequency, in Hz |
msDuration | pulse duration, in milliseconds. |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Adds a new volume transition to the playing sequence.
js | function addVolMoveToPlaySeq( | volume, msDuration) |
cpp | int addVolMoveToPlaySeq( | int volume, int msDuration) |
m | -(int) addVolMoveToPlaySeq | : (int) volume |
: (int) msDuration |
pas | LongInt addVolMoveToPlaySeq( | volume: LongInt, |
msDuration: LongInt): LongInt |
vb | function addVolMoveToPlaySeq( | ByVal volume As Integer, |
ByVal msDuration As Integer) As Integer |
cs | int addVolMoveToPlaySeq( | int volume, int msDuration) |
java | int addVolMoveToPlaySeq( | int volume, int msDuration) |
uwp | async Task<int> addVolMoveToPlaySeq( | int volume, int msDuration) |
py | addVolMoveToPlaySeq( | volume, msDuration) |
php | function addVolMoveToPlaySeq( | $volume, $msDuration) |
ts | async addVolMoveToPlaySeq( | volume: number, msDuration: number): Promise<number> |
es | async addVolMoveToPlaySeq( | volume, msDuration) |
dnp | int addVolMoveToPlaySeq( | int volume, int msDuration) |
cp | int addVolMoveToPlaySeq( | int volume, int msDuration) |
cmd | YBuzzer target addVolMoveToPlaySeq | volume msDuration |
Frequency stays untouched: if frequency is at zero, the transition has no effect.
Parameters :
volume | desired volume when the transition is completed, as a percentage. |
msDuration | duration of the volume transition, in milliseconds. |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Invalidates the cache.
js | function clearCache( | ) |
cpp | void clearCache( | ) |
m | -(void) clearCache |
pas | clearCache( | ) |
vb | procedure clearCache( | ) |
cs | void clearCache( | ) |
java | void clearCache( | ) |
py | clearCache( | ) |
php | function clearCache( | ) |
ts | async clearCache( | ): Promise<void> |
es | async clearCache( | ) |
Invalidates the cache of the buzzer attributes. Forces the next call to get_xxx() or loadxxx() to use values that come from the device.
Returns a short text that describes unambiguously the instance of the buzzer in the form TYPE(NAME)=SERIAL.FUNCTIONID.
js | function describe( | ) |
cpp | string describe( | ) |
m | -(NSString*) describe |
pas | string describe( | ): string |
vb | function describe( | ) As String |
cs | string describe( | ) |
java | String describe( | ) |
py | describe( | ) |
php | function describe( | ) |
ts | async describe( | ): Promise<string> |
es | async describe( | ) |
More precisely, TYPE is the type of the function, NAME it the name used for the first access to the function, SERIAL is the serial number of the module if the module is connected or "unresolved", and FUNCTIONID is the hardware identifier of the function if the module is connected. For example, this method returns Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1 if the module is already connected or Relay(BadCustomeName.relay1)=unresolved if the module has not yet been connected. This method does not trigger any USB or TCP transaction and can therefore be used in a debugger.
Returns :
a string that describes the buzzer (ex: Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1)
Makes the buzzer frequency change over a period of time.
js | function freqMove( | frequency, duration) |
cpp | int freqMove( | int frequency, int duration) |
m | -(int) freqMove | : (int) frequency |
: (int) duration |
pas | LongInt freqMove( | frequency: LongInt, duration: LongInt): LongInt |
vb | function freqMove( | ByVal frequency As Integer, ByVal duration As Integer) As Integer |
cs | int freqMove( | int frequency, int duration) |
java | int freqMove( | int frequency, int duration) |
uwp | async Task<int> freqMove( | int frequency, int duration) |
py | freqMove( | frequency, duration) |
php | function freqMove( | $frequency, $duration) |
ts | async freqMove( | frequency: number, duration: number): Promise<number> |
es | async freqMove( | frequency, duration) |
dnp | int freqMove( | int frequency, int duration) |
cp | int freqMove( | int frequency, int duration) |
cmd | YBuzzer target freqMove | frequency duration |
Parameters :
frequency | frequency to reach, in hertz. A frequency under 25Hz stops the buzzer. |
duration | pulse duration in milliseconds |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Returns the current value of the buzzer (no more than 6 characters).
js | function get_advertisedValue( | ) |
cpp | string get_advertisedValue( | ) |
m | -(NSString*) advertisedValue |
pas | string get_advertisedValue( | ): string |
vb | function get_advertisedValue( | ) As String |
cs | string get_advertisedValue( | ) |
java | String get_advertisedValue( | ) |
uwp | async Task<string> get_advertisedValue( | ) |
py | get_advertisedValue( | ) |
php | function get_advertisedValue( | ) |
ts | async get_advertisedValue( | ): Promise<string> |
es | async get_advertisedValue( | ) |
dnp | string get_advertisedValue( | ) |
cp | string get_advertisedValue( | ) |
cmd | YBuzzer target get_advertisedValue |
Returns :
a string corresponding to the current value of the buzzer (no more than 6 characters).
On failure, throws an exception or returns YBuzzer.ADVERTISEDVALUE_INVALID.
Returns the error message of the latest error with the buzzer.
js | function get_errorMessage( | ) |
cpp | string get_errorMessage( | ) |
m | -(NSString*) errorMessage |
pas | string get_errorMessage( | ): string |
vb | function get_errorMessage( | ) As String |
cs | string get_errorMessage( | ) |
java | String get_errorMessage( | ) |
py | get_errorMessage( | ) |
php | function get_errorMessage( | ) |
ts | get_errorMessage( | ): string |
es | get_errorMessage( | ) |
This method is mostly useful when using the Yoctopuce library with exceptions disabled.
Returns :
a string corresponding to the latest error message that occured while using the buzzer object
Returns the numerical error code of the latest error with the buzzer.
js | function get_errorType( | ) |
cpp | YRETCODE get_errorType( | ) |
m | -(YRETCODE) errorType |
pas | YRETCODE get_errorType( | ): YRETCODE |
vb | function get_errorType( | ) As YRETCODE |
cs | YRETCODE get_errorType( | ) |
java | int get_errorType( | ) |
py | get_errorType( | ) |
php | function get_errorType( | ) |
ts | get_errorType( | ): number |
es | get_errorType( | ) |
This method is mostly useful when using the Yoctopuce library with exceptions disabled.
Returns :
a number corresponding to the code of the latest error that occurred while using the buzzer object
Returns the frequency of the signal sent to the buzzer/speaker.
js | function get_frequency( | ) |
cpp | double get_frequency( | ) |
m | -(double) frequency |
pas | double get_frequency( | ): double |
vb | function get_frequency( | ) As Double |
cs | double get_frequency( | ) |
java | double get_frequency( | ) |
uwp | async Task<double> get_frequency( | ) |
py | get_frequency( | ) |
php | function get_frequency( | ) |
ts | async get_frequency( | ): Promise<number> |
es | async get_frequency( | ) |
dnp | double get_frequency( | ) |
cp | double get_frequency( | ) |
cmd | YBuzzer target get_frequency |
Returns :
a floating point number corresponding to the frequency of the signal sent to the buzzer/speaker
On failure, throws an exception or returns YBuzzer.FREQUENCY_INVALID.
Returns a global identifier of the buzzer in the format MODULE_NAME.FUNCTION_NAME.
js | function get_friendlyName( | ) |
cpp | string get_friendlyName( | ) |
m | -(NSString*) friendlyName |
cs | string get_friendlyName( | ) |
java | String get_friendlyName( | ) |
py | get_friendlyName( | ) |
php | function get_friendlyName( | ) |
ts | async get_friendlyName( | ): Promise<string> |
es | async get_friendlyName( | ) |
dnp | string get_friendlyName( | ) |
cp | string get_friendlyName( | ) |
The returned string uses the logical names of the module and of the buzzer if they are defined, otherwise the serial number of the module and the hardware identifier of the buzzer (for example: MyCustomName.relay1)
Returns :
a string that uniquely identifies the buzzer using logical names (ex: MyCustomName.relay1)
On failure, throws an exception or returns YBuzzer.FRIENDLYNAME_INVALID.
Returns a unique identifier of type YFUN_DESCR corresponding to the function.
js | function get_functionDescriptor( | ) |
cpp | YFUN_DESCR get_functionDescriptor( | ) |
m | -(YFUN_DESCR) functionDescriptor |
pas | YFUN_DESCR get_functionDescriptor( | ): YFUN_DESCR |
vb | function get_functionDescriptor( | ) As YFUN_DESCR |
cs | YFUN_DESCR get_functionDescriptor( | ) |
java | String get_functionDescriptor( | ) |
py | get_functionDescriptor( | ) |
php | function get_functionDescriptor( | ) |
ts | async get_functionDescriptor( | ): Promise<string> |
es | async get_functionDescriptor( | ) |
This identifier can be used to test if two instances of YFunction reference the same physical function on the same physical device.
Returns :
an identifier of type YFUN_DESCR.
If the function has never been contacted, the returned value is Y$CLASSNAME$.FUNCTIONDESCRIPTOR_INVALID.
Returns the hardware identifier of the buzzer, without reference to the module.
js | function get_functionId( | ) |
cpp | string get_functionId( | ) |
m | -(NSString*) functionId |
vb | function get_functionId( | ) As String |
cs | string get_functionId( | ) |
java | String get_functionId( | ) |
py | get_functionId( | ) |
php | function get_functionId( | ) |
ts | async get_functionId( | ): Promise<string> |
es | async get_functionId( | ) |
dnp | string get_functionId( | ) |
cp | string get_functionId( | ) |
For example relay1
Returns :
a string that identifies the buzzer (ex: relay1)
On failure, throws an exception or returns YBuzzer.FUNCTIONID_INVALID.
Returns the unique hardware identifier of the buzzer in the form SERIAL.FUNCTIONID.
js | function get_hardwareId( | ) |
cpp | string get_hardwareId( | ) |
m | -(NSString*) hardwareId |
vb | function get_hardwareId( | ) As String |
cs | string get_hardwareId( | ) |
java | String get_hardwareId( | ) |
py | get_hardwareId( | ) |
php | function get_hardwareId( | ) |
ts | async get_hardwareId( | ): Promise<string> |
es | async get_hardwareId( | ) |
dnp | string get_hardwareId( | ) |
cp | string get_hardwareId( | ) |
The unique hardware identifier is composed of the device serial number and of the hardware identifier of the buzzer (for example RELAYLO1-123456.relay1).
Returns :
a string that uniquely identifies the buzzer (ex: RELAYLO1-123456.relay1)
On failure, throws an exception or returns YBuzzer.HARDWAREID_INVALID.
Returns the logical name of the buzzer.
js | function get_logicalName( | ) |
cpp | string get_logicalName( | ) |
m | -(NSString*) logicalName |
pas | string get_logicalName( | ): string |
vb | function get_logicalName( | ) As String |
cs | string get_logicalName( | ) |
java | String get_logicalName( | ) |
uwp | async Task<string> get_logicalName( | ) |
py | get_logicalName( | ) |
php | function get_logicalName( | ) |
ts | async get_logicalName( | ): Promise<string> |
es | async get_logicalName( | ) |
dnp | string get_logicalName( | ) |
cp | string get_logicalName( | ) |
cmd | YBuzzer target get_logicalName |
Returns :
a string corresponding to the logical name of the buzzer.
On failure, throws an exception or returns YBuzzer.LOGICALNAME_INVALID.
Gets the YModule object for the device on which the function is located.
js | function get_module( | ) |
cpp | YModule * get_module( | ) |
m | -(YModule*) module |
pas | TYModule get_module( | ): TYModule |
vb | function get_module( | ) As YModule |
cs | YModule get_module( | ) |
java | YModule get_module( | ) |
py | get_module( | ) |
php | function get_module( | ) |
ts | async get_module( | ): Promise<YModule> |
es | async get_module( | ) |
dnp | YModuleProxy get_module( | ) |
cp | YModuleProxy * get_module( | ) |
If the function cannot be located on any module, the returned instance of YModule is not shown as on-line.
Returns :
an instance of YModule
Gets the YModule object for the device on which the function is located (asynchronous version).
js | function get_module_async( | callback, context) |
If the function cannot be located on any module, the returned YModule object does not show as on-line.
This asynchronous version exists only in JavaScript. It uses a callback instead of a return value in order to avoid blocking Firefox JavaScript VM that does not implement context switching during blocking I/O calls. See the documentation section on asynchronous JavasSript calls for more details.
Parameters :
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving function object and the requested YModule object |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Returns the maximum length of the playing sequence.
js | function get_playSeqMaxSize( | ) |
cpp | int get_playSeqMaxSize( | ) |
m | -(int) playSeqMaxSize |
pas | LongInt get_playSeqMaxSize( | ): LongInt |
vb | function get_playSeqMaxSize( | ) As Integer |
cs | int get_playSeqMaxSize( | ) |
java | int get_playSeqMaxSize( | ) |
uwp | async Task<int> get_playSeqMaxSize( | ) |
py | get_playSeqMaxSize( | ) |
php | function get_playSeqMaxSize( | ) |
ts | async get_playSeqMaxSize( | ): Promise<number> |
es | async get_playSeqMaxSize( | ) |
dnp | int get_playSeqMaxSize( | ) |
cp | int get_playSeqMaxSize( | ) |
cmd | YBuzzer target get_playSeqMaxSize |
Returns :
an integer corresponding to the maximum length of the playing sequence
On failure, throws an exception or returns YBuzzer.PLAYSEQMAXSIZE_INVALID.
Returns the playing sequence signature.
js | function get_playSeqSignature( | ) |
cpp | int get_playSeqSignature( | ) |
m | -(int) playSeqSignature |
pas | LongInt get_playSeqSignature( | ): LongInt |
vb | function get_playSeqSignature( | ) As Integer |
cs | int get_playSeqSignature( | ) |
java | int get_playSeqSignature( | ) |
uwp | async Task<int> get_playSeqSignature( | ) |
py | get_playSeqSignature( | ) |
php | function get_playSeqSignature( | ) |
ts | async get_playSeqSignature( | ): Promise<number> |
es | async get_playSeqSignature( | ) |
dnp | int get_playSeqSignature( | ) |
cp | int get_playSeqSignature( | ) |
cmd | YBuzzer target get_playSeqSignature |
As playing sequences cannot be read from the device, this can be used to detect if a specific playing sequence is already programmed.
Returns :
an integer corresponding to the playing sequence signature
On failure, throws an exception or returns YBuzzer.PLAYSEQSIGNATURE_INVALID.
Returns the current length of the playing sequence.
js | function get_playSeqSize( | ) |
cpp | int get_playSeqSize( | ) |
m | -(int) playSeqSize |
pas | LongInt get_playSeqSize( | ): LongInt |
vb | function get_playSeqSize( | ) As Integer |
cs | int get_playSeqSize( | ) |
java | int get_playSeqSize( | ) |
uwp | async Task<int> get_playSeqSize( | ) |
py | get_playSeqSize( | ) |
php | function get_playSeqSize( | ) |
ts | async get_playSeqSize( | ): Promise<number> |
es | async get_playSeqSize( | ) |
dnp | int get_playSeqSize( | ) |
cp | int get_playSeqSize( | ) |
cmd | YBuzzer target get_playSeqSize |
Returns :
an integer corresponding to the current length of the playing sequence
On failure, throws an exception or returns YBuzzer.PLAYSEQSIZE_INVALID.
Returns the serial number of the module, as set by the factory.
js | function get_serialNumber( | ) |
cpp | string get_serialNumber( | ) |
m | -(NSString*) serialNumber |
pas | string get_serialNumber( | ): string |
vb | function get_serialNumber( | ) As String |
cs | string get_serialNumber( | ) |
java | String get_serialNumber( | ) |
uwp | async Task<string> get_serialNumber( | ) |
py | get_serialNumber( | ) |
php | function get_serialNumber( | ) |
ts | async get_serialNumber( | ): Promise<string> |
es | async get_serialNumber( | ) |
dnp | string get_serialNumber( | ) |
cp | string get_serialNumber( | ) |
cmd | YBuzzer target get_serialNumber |
Returns :
a string corresponding to the serial number of the module, as set by the factory.
On failure, throws an exception or returns YFunction.SERIALNUMBER_INVALID.
Returns the value of the userData attribute, as previously stored using method set_userData.
js | function get_userData( | ) |
cpp | void * get_userData( | ) |
m | -(id) userData |
pas | Tobject get_userData( | ): Tobject |
vb | function get_userData( | ) As Object |
cs | object get_userData( | ) |
java | Object get_userData( | ) |
py | get_userData( | ) |
php | function get_userData( | ) |
ts | async get_userData( | ): Promise<object|null> |
es | async get_userData( | ) |
This attribute is never touched directly by the API, and is at disposal of the caller to store a context.
Returns :
the object stored previously by the caller.
Returns the volume of the signal sent to the buzzer/speaker.
js | function get_volume( | ) |
cpp | int get_volume( | ) |
m | -(int) volume |
pas | LongInt get_volume( | ): LongInt |
vb | function get_volume( | ) As Integer |
cs | int get_volume( | ) |
java | int get_volume( | ) |
uwp | async Task<int> get_volume( | ) |
py | get_volume( | ) |
php | function get_volume( | ) |
ts | async get_volume( | ): Promise<number> |
es | async get_volume( | ) |
dnp | int get_volume( | ) |
cp | int get_volume( | ) |
cmd | YBuzzer target get_volume |
Returns :
an integer corresponding to the volume of the signal sent to the buzzer/speaker
On failure, throws an exception or returns YBuzzer.VOLUME_INVALID.
Checks if the buzzer is currently reachable, without raising any error.
js | function isOnline( | ) |
cpp | bool isOnline( | ) |
m | -(BOOL) isOnline |
pas | boolean isOnline( | ): boolean |
vb | function isOnline( | ) As Boolean |
cs | bool isOnline( | ) |
java | boolean isOnline( | ) |
py | isOnline( | ) |
php | function isOnline( | ) |
ts | async isOnline( | ): Promise<boolean> |
es | async isOnline( | ) |
dnp | bool isOnline( | ) |
cp | bool isOnline( | ) |
If there is a cached value for the buzzer in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the buzzer.
Returns :
true if the buzzer can be reached, and false otherwise
Checks if the buzzer is currently reachable, without raising any error (asynchronous version).
js | function isOnline_async( | callback, context) |
If there is a cached value for the buzzer in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the requested function.
This asynchronous version exists only in Javascript. It uses a callback instead of a return value in order to avoid blocking the Javascript virtual machine.
Parameters :
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving function object and the boolean result |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Test if the function is readOnly.
cpp | bool isReadOnly( | ) |
m | -(bool) isReadOnly |
pas | boolean isReadOnly( | ): boolean |
vb | function isReadOnly( | ) As Boolean |
cs | bool isReadOnly( | ) |
java | boolean isReadOnly( | ) |
uwp | async Task<bool> isReadOnly( | ) |
py | isReadOnly( | ) |
php | function isReadOnly( | ) |
ts | async isReadOnly( | ): Promise<boolean> |
es | async isReadOnly( | ) |
dnp | bool isReadOnly( | ) |
cp | bool isReadOnly( | ) |
cmd | YBuzzer target isReadOnly |
Return true if the function is write protected or that the function is not available.
Returns :
true if the function is readOnly or not online.
Preloads the buzzer cache with a specified validity duration.
js | function load( | msValidity) |
cpp | YRETCODE load( | int msValidity) |
m | -(YRETCODE) load | : (u64) msValidity |
pas | YRETCODE load( | msValidity: u64): YRETCODE |
vb | function load( | ByVal msValidity As Long) As YRETCODE |
cs | YRETCODE load( | ulong msValidity) |
java | int load( | long msValidity) |
py | load( | msValidity) |
php | function load( | $msValidity) |
ts | async load( | msValidity: number): Promise<number> |
es | async load( | msValidity) |
By default, whenever accessing a device, all function attributes are kept in cache for the standard duration (5 ms). This method can be used to temporarily mark the cache as valid for a longer period, in order to reduce network traffic for instance.
Parameters :
msValidity | an integer corresponding to the validity attributed to the loaded function parameters, in milliseconds |
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Returns the current value of a single function attribute, as a text string, as quickly as possible but without using the cached value.
js | function loadAttribute( | attrName) |
cpp | string loadAttribute( | string attrName) |
m | -(NSString*) loadAttribute | : (NSString*) attrName |
pas | string loadAttribute( | attrName: string): string |
vb | function loadAttribute( | ByVal attrName As String) As String |
cs | string loadAttribute( | string attrName) |
java | String loadAttribute( | String attrName) |
uwp | async Task<string> loadAttribute( | string attrName) |
py | loadAttribute( | attrName) |
php | function loadAttribute( | $attrName) |
ts | async loadAttribute( | attrName: string): Promise<string> |
es | async loadAttribute( | attrName) |
dnp | string loadAttribute( | string attrName) |
cp | string loadAttribute( | string attrName) |
Parameters :
attrName | the name of the requested attribute |
Returns :
a string with the value of the the attribute
On failure, throws an exception or returns an empty string.
Preloads the buzzer cache with a specified validity duration (asynchronous version).
js | function load_async( | msValidity, callback, context) |
By default, whenever accessing a device, all function attributes are kept in cache for the standard duration (5 ms). This method can be used to temporarily mark the cache as valid for a longer period, in order to reduce network traffic for instance.
This asynchronous version exists only in JavaScript. It uses a callback instead of a return value in order to avoid blocking the JavaScript virtual machine.
Parameters :
msValidity | an integer corresponding to the validity of the loaded function parameters, in milliseconds |
callback | callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving function object and the error code (or YAPI.SUCCESS) |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing : the result is provided to the callback.
Disables the propagation of every new advertised value to the parent hub.
js | function muteValueCallbacks( | ) |
cpp | int muteValueCallbacks( | ) |
m | -(int) muteValueCallbacks |
pas | LongInt muteValueCallbacks( | ): LongInt |
vb | function muteValueCallbacks( | ) As Integer |
cs | int muteValueCallbacks( | ) |
java | int muteValueCallbacks( | ) |
uwp | async Task<int> muteValueCallbacks( | ) |
py | muteValueCallbacks( | ) |
php | function muteValueCallbacks( | ) |
ts | async muteValueCallbacks( | ): Promise<number> |
es | async muteValueCallbacks( | ) |
dnp | int muteValueCallbacks( | ) |
cp | int muteValueCallbacks( | ) |
cmd | YBuzzer target muteValueCallbacks |
You can use this function to save bandwidth and CPU on computers with limited resources, or to prevent unwanted invocations of the HTTP callback. Remember to call the saveToFlash() method of the module if the modification must be kept.
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Continues the enumeration of buzzers started using yFirstBuzzer().
js | function nextBuzzer( | ) |
cpp | YBuzzer * nextBuzzer( | ) |
m | -(nullable YBuzzer*) nextBuzzer |
pas | TYBuzzer nextBuzzer( | ): TYBuzzer |
vb | function nextBuzzer( | ) As YBuzzer |
cs | YBuzzer nextBuzzer( | ) |
java | YBuzzer nextBuzzer( | ) |
uwp | YBuzzer nextBuzzer( | ) |
py | nextBuzzer( | ) |
php | function nextBuzzer( | ) |
ts | nextBuzzer( | ): YBuzzer | null |
es | nextBuzzer( | ) |
Caution: You can't make any assumption about the returned buzzers order. If you want to find a specific a buzzer, use Buzzer.findBuzzer() and a hardwareID or a logical name.
Returns :
a pointer to a YBuzzer object, corresponding to a buzzer currently online, or a null pointer if there are no more buzzers to enumerate.
Starts the preprogrammed playing sequence and run it once only.
js | function oncePlaySeq( | ) |
cpp | int oncePlaySeq( | ) |
m | -(int) oncePlaySeq |
pas | LongInt oncePlaySeq( | ): LongInt |
vb | function oncePlaySeq( | ) As Integer |
cs | int oncePlaySeq( | ) |
java | int oncePlaySeq( | ) |
uwp | async Task<int> oncePlaySeq( | ) |
py | oncePlaySeq( | ) |
php | function oncePlaySeq( | ) |
ts | async oncePlaySeq( | ): Promise<number> |
es | async oncePlaySeq( | ) |
dnp | int oncePlaySeq( | ) |
cp | int oncePlaySeq( | ) |
cmd | YBuzzer target oncePlaySeq |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Immediately play a note sequence.
js | function playNotes( | notes) |
cpp | int playNotes( | string notes) |
m | -(int) playNotes | : (NSString*) notes |
pas | LongInt playNotes( | notes: string): LongInt |
vb | function playNotes( | ByVal notes As String) As Integer |
cs | int playNotes( | string notes) |
java | int playNotes( | String notes) |
uwp | async Task<int> playNotes( | string notes) |
py | playNotes( | notes) |
php | function playNotes( | $notes) |
ts | async playNotes( | notes: string): Promise<number> |
es | async playNotes( | notes) |
dnp | int playNotes( | string notes) |
cp | int playNotes( | string notes) |
cmd | YBuzzer target playNotes | notes |
Notes are provided as text words, separated by spaces. The pitch is specified using the usual letter from A to G. The duration is specified as the divisor of a whole note: 4 for a fourth, 8 for an eight note, etc. Some modifiers are supported: # and b to alter a note pitch, ' and , to move to the upper/lower octave, . to enlarge the note duration.
Parameters :
notes | notes to be played, as a text string. |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Activates the buzzer for a short duration.
js | function pulse( | frequency, duration) |
cpp | int pulse( | int frequency, int duration) |
m | -(int) pulse | : (int) frequency |
: (int) duration |
pas | LongInt pulse( | frequency: LongInt, duration: LongInt): LongInt |
vb | function pulse( | ByVal frequency As Integer, ByVal duration As Integer) As Integer |
cs | int pulse( | int frequency, int duration) |
java | int pulse( | int frequency, int duration) |
uwp | async Task<int> pulse( | int frequency, int duration) |
py | pulse( | frequency, duration) |
php | function pulse( | $frequency, $duration) |
ts | async pulse( | frequency: number, duration: number): Promise<number> |
es | async pulse( | frequency, duration) |
dnp | int pulse( | int frequency, int duration) |
cp | int pulse( | int frequency, int duration) |
cmd | YBuzzer target pulse | frequency duration |
Parameters :
frequency | pulse frequency, in hertz |
duration | pulse duration in milliseconds |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Registers the callback function that is invoked on every change of advertised value.
js | function registerValueCallback( | callback) |
cpp | int registerValueCallback( | YBuzzerValueCallback callback) |
m | -(int) registerValueCallback | : (YBuzzerValueCallback _Nullable) callback |
pas | LongInt registerValueCallback( | callback: TYBuzzerValueCallback): LongInt |
vb | function registerValueCallback( | ByVal callback As YBuzzerValueCallback) As Integer |
cs | int registerValueCallback( | ValueCallback callback) |
java | int registerValueCallback( | UpdateCallback callback) |
uwp | async Task<int> registerValueCallback( | ValueCallback callback) |
py | registerValueCallback( | callback) |
php | function registerValueCallback( | $callback) |
ts | async registerValueCallback( | callback: YBuzzerValueCallback | null): Promise<number> |
es | async registerValueCallback( | callback) |
The callback is invoked only during the execution of ySleep or yHandleEvents. This provides control over the time when the callback is triggered. For good responsiveness, remember to call one of these two functions periodically. To unregister a callback, pass a null pointer as argument.
Parameters :
callback | the callback function to call, or a null pointer. The callback function should take two arguments: the function object of which the value has changed, and the character string describing the new advertised value. |
Reloads the preprogrammed playing sequence from the flash memory.
js | function reloadPlaySeq( | ) |
cpp | int reloadPlaySeq( | ) |
m | -(int) reloadPlaySeq |
pas | LongInt reloadPlaySeq( | ): LongInt |
vb | function reloadPlaySeq( | ) As Integer |
cs | int reloadPlaySeq( | ) |
java | int reloadPlaySeq( | ) |
uwp | async Task<int> reloadPlaySeq( | ) |
py | reloadPlaySeq( | ) |
php | function reloadPlaySeq( | ) |
ts | async reloadPlaySeq( | ): Promise<number> |
es | async reloadPlaySeq( | ) |
dnp | int reloadPlaySeq( | ) |
cp | int reloadPlaySeq( | ) |
cmd | YBuzzer target reloadPlaySeq |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Resets the preprogrammed playing sequence and sets the frequency to zero.
js | function resetPlaySeq( | ) |
cpp | int resetPlaySeq( | ) |
m | -(int) resetPlaySeq |
pas | LongInt resetPlaySeq( | ): LongInt |
vb | function resetPlaySeq( | ) As Integer |
cs | int resetPlaySeq( | ) |
java | int resetPlaySeq( | ) |
uwp | async Task<int> resetPlaySeq( | ) |
py | resetPlaySeq( | ) |
php | function resetPlaySeq( | ) |
ts | async resetPlaySeq( | ): Promise<number> |
es | async resetPlaySeq( | ) |
dnp | int resetPlaySeq( | ) |
cp | int resetPlaySeq( | ) |
cmd | YBuzzer target resetPlaySeq |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Saves the preprogrammed playing sequence to flash memory.
js | function savePlaySeq( | ) |
cpp | int savePlaySeq( | ) |
m | -(int) savePlaySeq |
pas | LongInt savePlaySeq( | ): LongInt |
vb | function savePlaySeq( | ) As Integer |
cs | int savePlaySeq( | ) |
java | int savePlaySeq( | ) |
uwp | async Task<int> savePlaySeq( | ) |
py | savePlaySeq( | ) |
php | function savePlaySeq( | ) |
ts | async savePlaySeq( | ): Promise<number> |
es | async savePlaySeq( | ) |
dnp | int savePlaySeq( | ) |
cp | int savePlaySeq( | ) |
cmd | YBuzzer target savePlaySeq |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Changes the frequency of the signal sent to the buzzer.
js | function set_frequency( | newval) |
cpp | int set_frequency( | double newval) |
m | -(int) setFrequency | : (double) newval |
pas | integer set_frequency( | newval: double): integer |
vb | function set_frequency( | ByVal newval As Double) As Integer |
cs | int set_frequency( | double newval) |
java | int set_frequency( | double newval) |
uwp | async Task<int> set_frequency( | double newval) |
py | set_frequency( | newval) |
php | function set_frequency( | $newval) |
ts | async set_frequency( | newval: number): Promise<number> |
es | async set_frequency( | newval) |
dnp | int set_frequency( | double newval) |
cp | int set_frequency( | double newval) |
cmd | YBuzzer target set_frequency | newval |
A zero value stops the buzzer.
Parameters :
newval | a floating point number corresponding to the frequency of the signal sent to the buzzer |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Changes the logical name of the buzzer.
js | function set_logicalName( | newval) |
cpp | int set_logicalName( | string newval) |
m | -(int) setLogicalName | : (NSString*) newval |
pas | integer set_logicalName( | newval: string): integer |
vb | function set_logicalName( | ByVal newval As String) As Integer |
cs | int set_logicalName( | string newval) |
java | int set_logicalName( | String newval) |
uwp | async Task<int> set_logicalName( | string newval) |
py | set_logicalName( | newval) |
php | function set_logicalName( | $newval) |
ts | async set_logicalName( | newval: string): Promise<number> |
es | async set_logicalName( | newval) |
dnp | int set_logicalName( | string newval) |
cp | int set_logicalName( | string newval) |
cmd | YBuzzer target set_logicalName | newval |
You can use yCheckLogicalName() prior to this call to make sure that your parameter is valid. Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | a string corresponding to the logical name of the buzzer. |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Stores a user context provided as argument in the userData attribute of the function.
js | function set_userData( | data) |
cpp | void set_userData( | void * data) |
m | -(void) setUserData | : (id) data |
pas | set_userData( | data: Tobject) |
vb | procedure set_userData( | ByVal data As Object) |
cs | void set_userData( | object data) |
java | void set_userData( | Object data) |
py | set_userData( | data) |
php | function set_userData( | $data) |
ts | async set_userData( | data: object|null): Promise<void> |
es | async set_userData( | data) |
This attribute is never touched by the API, and is at disposal of the caller to store a context.
Parameters :
data | any kind of object to be stored |
Changes the volume of the signal sent to the buzzer/speaker.
js | function set_volume( | newval) |
cpp | int set_volume( | int newval) |
m | -(int) setVolume | : (int) newval |
pas | integer set_volume( | newval: LongInt): integer |
vb | function set_volume( | ByVal newval As Integer) As Integer |
cs | int set_volume( | int newval) |
java | int set_volume( | int newval) |
uwp | async Task<int> set_volume( | int newval) |
py | set_volume( | newval) |
php | function set_volume( | $newval) |
ts | async set_volume( | newval: number): Promise<number> |
es | async set_volume( | newval) |
dnp | int set_volume( | int newval) |
cp | int set_volume( | int newval) |
cmd | YBuzzer target set_volume | newval |
Remember to call the saveToFlash() method of the module if the modification must be kept.
Parameters :
newval | an integer corresponding to the volume of the signal sent to the buzzer/speaker |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Starts the preprogrammed playing sequence.
js | function startPlaySeq( | ) |
cpp | int startPlaySeq( | ) |
m | -(int) startPlaySeq |
pas | LongInt startPlaySeq( | ): LongInt |
vb | function startPlaySeq( | ) As Integer |
cs | int startPlaySeq( | ) |
java | int startPlaySeq( | ) |
uwp | async Task<int> startPlaySeq( | ) |
py | startPlaySeq( | ) |
php | function startPlaySeq( | ) |
ts | async startPlaySeq( | ): Promise<number> |
es | async startPlaySeq( | ) |
dnp | int startPlaySeq( | ) |
cp | int startPlaySeq( | ) |
cmd | YBuzzer target startPlaySeq |
The sequence runs in loop until it is stopped by stopPlaySeq or an explicit change. To play the sequence only once, use oncePlaySeq().
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Stops the preprogrammed playing sequence and sets the frequency to zero.
js | function stopPlaySeq( | ) |
cpp | int stopPlaySeq( | ) |
m | -(int) stopPlaySeq |
pas | LongInt stopPlaySeq( | ): LongInt |
vb | function stopPlaySeq( | ) As Integer |
cs | int stopPlaySeq( | ) |
java | int stopPlaySeq( | ) |
uwp | async Task<int> stopPlaySeq( | ) |
py | stopPlaySeq( | ) |
php | function stopPlaySeq( | ) |
ts | async stopPlaySeq( | ): Promise<number> |
es | async stopPlaySeq( | ) |
dnp | int stopPlaySeq( | ) |
cp | int stopPlaySeq( | ) |
cmd | YBuzzer target stopPlaySeq |
Returns :
YAPI.SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.
Re-enables the propagation of every new advertised value to the parent hub.
js | function unmuteValueCallbacks( | ) |
cpp | int unmuteValueCallbacks( | ) |
m | -(int) unmuteValueCallbacks |
pas | LongInt unmuteValueCallbacks( | ): LongInt |
vb | function unmuteValueCallbacks( | ) As Integer |
cs | int unmuteValueCallbacks( | ) |
java | int unmuteValueCallbacks( | ) |
uwp | async Task<int> unmuteValueCallbacks( | ) |
py | unmuteValueCallbacks( | ) |
php | function unmuteValueCallbacks( | ) |
ts | async unmuteValueCallbacks( | ): Promise<number> |
es | async unmuteValueCallbacks( | ) |
dnp | int unmuteValueCallbacks( | ) |
cp | int unmuteValueCallbacks( | ) |
cmd | YBuzzer target unmuteValueCallbacks |
This function reverts the effect of a previous call to muteValueCallbacks(). Remember to call the saveToFlash() method of the module if the modification must be kept.
Returns :
YAPI.SUCCESS when the call succeeds.
On failure, throws an exception or returns a negative error code.
Makes the buzzer volume change over a period of time, frequency stays untouched.
js | function volumeMove( | volume, duration) |
cpp | int volumeMove( | int volume, int duration) |
m | -(int) volumeMove | : (int) volume |
: (int) duration |
pas | LongInt volumeMove( | volume: LongInt, duration: LongInt): LongInt |
vb | function volumeMove( | ByVal volume As Integer, ByVal duration As Integer) As Integer |
cs | int volumeMove( | int volume, int duration) |
java | int volumeMove( | int volume, int duration) |
uwp | async Task<int> volumeMove( | int volume, int duration) |
py | volumeMove( | volume, duration) |
php | function volumeMove( | $volume, $duration) |
ts | async volumeMove( | volume: number, duration: number): Promise<number> |
es | async volumeMove( | volume, duration) |
dnp | int volumeMove( | int volume, int duration) |
cp | int volumeMove( | int volume, int duration) |
cmd | YBuzzer target volumeMove | volume duration |
Parameters :
volume | volume to reach in % |
duration | change duration in milliseconds |
Returns :
YAPI.SUCCESS if the call succeeds.
On failure, throws an exception or returns a negative error code.
Waits for all pending asynchronous commands on the module to complete, and invoke the user-provided callback function.
js | function wait_async( | callback, context) |
ts | wait_async( | callback: Function, context: object) |
es | wait_async( | callback, context) |
The callback function can therefore freely issue synchronous or asynchronous commands, without risking to block the JavaScript VM.
Parameters :
callback | callback function that is invoked when all pending commands on the module are completed. The callback function receives two arguments: the caller-specific context object and the receiving function object. |
context | caller-specific object that is passed as-is to the callback function |
Returns :
nothing.
Interface pour intéragir avec les LEDs RGB, disponibles par exemple dans le Yocto-Color-V2, le Yocto-MaxiBuzzer et le Yocto-PowerColor
La classe ColorLed permet de piloter une LED couleur. La couleur peut être spécifiée aussi bien en coordonnées RGB qu'en coordonnées HSL, les conversions RGB vers HSL étant faites automatiquement par le module. Ceci permet aisément d'allumer la LED avec une certaine teinte et d'en faire progressivement varier la saturation ou la luminosité. Si nécessaire, vous trouverez plus d'information sur la différence entre RGB et HSL dans la section suivante.
Pour utiliser les fonctions décrites ici, vous devez inclure:
es | in HTML: <script src="../../lib/yocto_colorled.js"></script> in node.js: require('yoctolib-es2017/yocto_colorled.js'); |
js | <script type='text/javascript' src='yocto_colorled.js'></script> |
cpp | #include "yocto_colorled.h" |
m | #import "yocto_colorled.h" |
pas | uses yocto_colorled; |
vb | yocto_colorled.vb |
cs | yocto_colorled.cs |
java | import com.yoctopuce.YoctoAPI.YColorLed; |
uwp | import com.yoctopuce.YoctoAPI.YColorLed; |
py | from yocto_colorled import * |
php | require_once('yocto_colorled.php'); |
ts | in HTML: import { YColorLed } from '../../dist/esm/yocto_colorled.js'; in Node.js: import { YColorLed } from 'yoctolib-cjs/yocto_colorled.js'; |
dnp | import YoctoProxyAPI.YColorLedProxy |
cp | #include "yocto_colorled_proxy.h" |
vi | YColorLed.vi |
ml | import YoctoProxyAPI.YColorLedProxy |
Fonction globales |
---|
YColorLed.FindColorLed(func) |
Permet de retrouver une LED RGB d'après un identifiant donné. |
YColorLed.FindColorLedInContext(yctx, func) |
Permet de retrouver une LED RGB d'après un identifiant donné dans un Context YAPI. |
YColorLed.FirstColorLed() |
Commence l'énumération des LEDs RGB accessibles par la librairie. |
YColorLed.FirstColorLedInContext(yctx) |
Commence l'énumération des LEDs RGB accessibles par la librairie. |
YColorLed.GetSimilarFunctions() |
Enumère toutes les fonctions de type ColorLed disponibles sur les modules actuellement joignables par la librairie, et retourne leurs identifiants matériels uniques (hardwareId). |
Propriétés des objets YColorLedProxy |
colorled→AdvertisedValue [lecture seule] |
Courte chaîne de caractères représentant l'état courant de la fonction. |
colorled→BlinkSeqMaxSize [lecture seule] |
Longueur maximum de la sequence de clignotement. |
colorled→FriendlyName [lecture seule] |
Identifiant global de la fonction au format NOM_MODULE.NOM_FONCTION. |
colorled→FunctionId [lecture seule] |
Identifiant matériel de la LED RGB, sans référence au module. |
colorled→HardwareId [lecture seule] |
Identifiant matériel unique de la fonction au format SERIAL.FUNCTIONID. |
colorled→HslColor [modifiable] |
Couleur HSL courante de la LED. |
colorled→IsOnline [lecture seule] |
Vérifie si le module hébergeant la fonction est joignable, sans déclencher d'erreur. |
colorled→LogicalName [modifiable] |
Nom logique de la fonction. |
colorled→RgbColor [modifiable] |
Couleur RGB courante de la LED. |
colorled→RgbColorAtPowerOn [modifiable] |
Couleur configurée pour être affichage à l'allumage du module. |
colorled→SerialNumber [lecture seule] |
Numéro de série du module, préprogrammé en usine. |
Méthodes des objets YColorLed |
colorled→addHslMoveToBlinkSeq(HSLcolor, msDelay) |
Ajoute une transition à la séquence de clignotement du module, la transition s'effectuera dans l'espace de couleur HSL. |
colorled→addRgbMoveToBlinkSeq(RGBcolor, msDelay) |
Ajoute une transition à la séquence de clignotement du module, la transition s'effectuera dans l'espace de couleur RGB |
colorled→clearCache() |
Invalide le cache. |
colorled→describe() |
Retourne un court texte décrivant de manière non-ambigüe l'instance de la LED RGB au format TYPE(NAME)=SERIAL.FUNCTIONID. |
colorled→get_advertisedValue() |
Retourne la valeur courante de la LED RGB (pas plus de 6 caractères). |
colorled→get_blinkSeqMaxSize() |
Retourne la longueur maximum de la sequence de clignotement. |
colorled→get_blinkSeqSignature() |
Retourne la signature de la signature de la séquence de clignotement. |
colorled→get_blinkSeqSize() |
Retourne la longueur actuelle de la sequence de clignotement. |
colorled→get_errorMessage() |
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation de la LED RGB. |
colorled→get_errorType() |
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation de la LED RGB. |
colorled→get_friendlyName() |
Retourne un identifiant global de la LED RGB au format NOM_MODULE.NOM_FONCTION. |
colorled→get_functionDescriptor() |
Retourne un identifiant unique de type YFUN_DESCR correspondant à la fonction. |
colorled→get_functionId() |
Retourne l'identifiant matériel de la LED RGB, sans référence au module. |
colorled→get_hardwareId() |
Retourne l'identifiant matériel unique de la LED RGB au format SERIAL.FUNCTIONID. |
colorled→get_hslColor() |
Retourne la couleur HSL courante de la LED. |
colorled→get_logicalName() |
Retourne le nom logique de la LED RGB. |
colorled→get_module() |
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction. |
colorled→get_module_async(callback, context) |
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction. |
colorled→get_rgbColor() |
Retourne la couleur RGB courante de la LED. |
colorled→get_rgbColorAtPowerOn() |
Retourne la couleur configurée pour être affichage à l'allumage du module. |
colorled→get_serialNumber() |
Retourne le numéro de série du module, préprogrammé en usine. |
colorled→get_userData() |
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData. |
colorled→hslMove(hsl_target, ms_duration) |
Effectue une transition continue dans l'espace HSL entre la couleur courante et une nouvelle couleur. |
colorled→isOnline() |
Vérifie si le module hébergeant la LED RGB est joignable, sans déclencher d'erreur. |
colorled→isOnline_async(callback, context) |
Vérifie si le module hébergeant la LED RGB est joignable, sans déclencher d'erreur. |
colorled→isReadOnly() |
Test si la fonction est en lecture seule. |
colorled→load(msValidity) |
Met en cache les valeurs courantes de la LED RGB, avec une durée de validité spécifiée. |
colorled→loadAttribute(attrName) |
Retourne la valeur actuelle d'un attribut spécifique de la fonction, sous forme de texte, le plus rapidement possible mais sans passer par le cache. |
colorled→load_async(msValidity, callback, context) |
Met en cache les valeurs courantes de la LED RGB, avec une durée de validité spécifiée. |
colorled→muteValueCallbacks() |
Désactive l'envoi de chaque changement de la valeur publiée au hub parent. |
colorled→nextColorLed() |
Continue l'énumération des LEDs RGB commencée à l'aide de yFirstColorLed() Attention, vous ne pouvez faire aucune supposition sur l'ordre dans lequel les LEDs RGB sont retournés. |
colorled→registerValueCallback(callback) |
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée. |
colorled→resetBlinkSeq() |
efface le contenu de la sequence de clignotement. |
colorled→rgbMove(rgb_target, ms_duration) |
Effectue une transition continue dans l'espace RGB entre la couleur courante et une nouvelle couleur. |
colorled→set_hslColor(newval) |
Modifie la couleur courante de la LED, en utilisant une couleur HSL spécifiée. |
colorled→set_logicalName(newval) |
Modifie le nom logique de la LED RGB. |
colorled→set_rgbColor(newval) |
Modifie la couleur courante de la LED, en utilisant une couleur RGB (Rouge Vert Bleu). |
colorled→set_rgbColorAtPowerOn(newval) |
Modifie la couleur que la LED va afficher à l'allumage du module. |
colorled→set_userData(data) |
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData. |
colorled→startBlinkSeq() |
Démarre l'exécution de la séquence préprogrammée de clignotement. |
colorled→stopBlinkSeq() |
Arrête l'exécution de la séquence préprogrammée de clignotement. |
colorled→unmuteValueCallbacks() |
Réactive l'envoi de chaque changement de la valeur publiée au hub parent. |
colorled→wait_async(callback, context) |
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre. |
Permet de retrouver une LED RGB d'après un identifiant donné.
js | function yFindColorLed( | func) |
cpp | YColorLed* FindColorLed( | string func) |
m | +(YColorLed*) FindColorLed | : (NSString*) func |
pas | TYColorLed yFindColorLed( | func: string): TYColorLed |
vb | function FindColorLed( | ByVal func As String) As YColorLed |
cs | static YColorLed FindColorLed( | string func) |
java | static YColorLed FindColorLed( | String func) |
uwp | static YColorLed FindColorLed( | string func) |
py | FindColorLed( | func) |
php | function FindColorLed( | $func) |
ts | static FindColorLed( | func: string): YColorLed |
es | static FindColorLed( | func) |
dnp | static YColorLedProxy FindColorLed( | string func) |
cp | static YColorLedProxy * FindColorLed( | string func) |
L'identifiant peut être spécifié sous plusieurs formes:
Cette fonction n'exige pas que la LED RGB soit en ligne au moment ou elle est appelée, l'objet retourné sera néanmoins valide. Utiliser la méthode YColorLed.isOnline() pour tester si la LED RGB est utilisable à un moment donné. En cas d'ambiguïté lorsqu'on fait une recherche par nom logique, aucune erreur ne sera notifiée: la première instance trouvée sera renvoyée. La recherche se fait d'abord par nom matériel, puis par nom logique.
Si un appel à la méthode is_online() de cet objet renvoie FAUX alors que vous êtes sûr que le module correspondant est bien branché, vérifiez que vous n'avez pas oublié d'appeler registerHub() à l'initialisation de de l'application.
Paramètres :
func | une chaîne de caractères qui référence la LED RGB sans ambiguïté, par exemple YRGBLED2.colorLed1. |
Retourne :
un objet de classe YColorLed qui permet ensuite de contrôler la LED RGB.
Permet de retrouver une LED RGB d'après un identifiant donné dans un Context YAPI.
java | static YColorLed FindColorLedInContext( | YAPIContext yctx, String func) |
uwp | static YColorLed FindColorLedInContext( | YAPIContext yctx, string func) |
ts | static FindColorLedInContext( | yctx: YAPIContext, func: string): YColorLed |
es | static FindColorLedInContext( | yctx, func) |
L'identifiant peut être spécifié sous plusieurs formes:
Cette fonction n'exige pas que la LED RGB soit en ligne au moment ou elle est appelée, l'objet retourné sera néanmoins valide. Utiliser la méthode YColorLed.isOnline() pour tester si la LED RGB est utilisable à un moment donné. En cas d'ambiguïté lorsqu'on fait une recherche par nom logique, aucune erreur ne sera notifiée: la première instance trouvée sera renvoyée. La recherche se fait d'abord par nom matériel, puis par nom logique.
Paramètres :
yctx | un contexte YAPI |
func | une chaîne de caractères qui référence la LED RGB sans ambiguïté, par exemple YRGBLED2.colorLed1. |
Retourne :
un objet de classe YColorLed qui permet ensuite de contrôler la LED RGB.
Commence l'énumération des LEDs RGB accessibles par la librairie.
js | function yFirstColorLed( | ) |
cpp | YColorLed * FirstColorLed( | ) |
m | +(YColorLed*) FirstColorLed |
pas | TYColorLed yFirstColorLed( | ): TYColorLed |
vb | function FirstColorLed( | ) As YColorLed |
cs | static YColorLed FirstColorLed( | ) |
java | static YColorLed FirstColorLed( | ) |
uwp | static YColorLed FirstColorLed( | ) |
py | FirstColorLed( | ) |
php | function FirstColorLed( | ) |
ts | static FirstColorLed( | ): YColorLed | null |
es | static FirstColorLed( | ) |
Utiliser la fonction YColorLed.nextColorLed() pour itérer sur les autres LEDs RGB.
Retourne :
un pointeur sur un objet YColorLed, correspondant à la première LED RGB accessible en ligne, ou null si il n'y a pas de LEDs RGB disponibles.
Commence l'énumération des LEDs RGB accessibles par la librairie.
java | static YColorLed FirstColorLedInContext( | YAPIContext yctx) |
uwp | static YColorLed FirstColorLedInContext( | YAPIContext yctx) |
ts | static FirstColorLedInContext( | yctx: YAPIContext): YColorLed | null |
es | static FirstColorLedInContext( | yctx) |
Utiliser la fonction YColorLed.nextColorLed() pour itérer sur les autres LEDs RGB.
Paramètres :
yctx | un contexte YAPI. |
Retourne :
un pointeur sur un objet YColorLed, correspondant à la première LED RGB accessible en ligne, ou null si il n'y a pas de LEDs RGB disponibles.
Enumère toutes les fonctions de type ColorLed disponibles sur les modules actuellement joignables par la librairie, et retourne leurs identifiants matériels uniques (hardwareId).
dnp | static new string[] GetSimilarFunctions( | ) |
cp | static vector<string> GetSimilarFunctions( | ) |
Chaque chaîne retournée peut être passée en argument à la méthode YColorLed.FindColorLed pour obtenir une objet permettant d'intéragir avec le module correspondant.
Retourne :
un tableau de chaînes de caractères, contenant les identifiants matériels de chaque fonction disponible trouvée.
Courte chaîne de caractères représentant l'état courant de la fonction.
dnp | string AdvertisedValue |
Longueur maximum de la sequence de clignotement.
dnp | int BlinkSeqMaxSize |
Identifiant global de la fonction au format NOM_MODULE.NOM_FONCTION.
dnp | string FriendlyName |
Le chaîne retournée utilise soit les noms logiques du module et de la fonction si ils sont définis, soit respectivement le numéro de série du module et l'identifant matériel de la fonction (par exemple: MyCustomName.relay1)
Identifiant matériel de la LED RGB, sans référence au module.
dnp | string FunctionId |
Par example relay1.
Identifiant matériel unique de la fonction au format SERIAL.FUNCTIONID.
dnp | string HardwareId |
L'identifiant unique est composé du numéro de série du module et de l'identifiant matériel de la fonction (par example RELAYLO1-123456.relay1).
Couleur HSL courante de la LED.
dnp | int HslColor |
Modifiable. Modifie la couleur courante de la LED, en utilisant une couleur HSL spécifiée. L'encodage est réalisé de la manière suivante: 0xHHSSLL.
Vérifie si le module hébergeant la fonction est joignable, sans déclencher d'erreur.
dnp | bool IsOnline |
Si les valeurs des attributs en cache de la fonction sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Nom logique de la fonction.
dnp | string LogicalName |
Modifiable. Vous pouvez utiliser yCheckLogicalName() pour vérifier si votre paramètre est valide. N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Couleur RGB courante de la LED.
dnp | int RgbColor |
Modifiable. Modifie la couleur courante de la LED, en utilisant une couleur RGB (Rouge Vert Bleu). L'encodage est réalisé de la manière suivante: 0xRRGGBB.
Couleur configurée pour être affichage à l'allumage du module.
dnp | int RgbColorAtPowerOn |
Modifiable. Modifie la couleur que la LED va afficher à l'allumage du module. N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Numéro de série du module, préprogrammé en usine.
dnp | string SerialNumber |
Ajoute une transition à la séquence de clignotement du module, la transition s'effectuera dans l'espace de couleur HSL.
js | function addHslMoveToBlinkSeq( | HSLcolor, msDelay) |
cpp | int addHslMoveToBlinkSeq( | int HSLcolor, int msDelay) |
m | -(int) addHslMoveToBlinkSeq | : (int) HSLcolor |
: (int) msDelay |
pas | LongInt addHslMoveToBlinkSeq( | HSLcolor: LongInt, |
msDelay: LongInt): LongInt |
vb | function addHslMoveToBlinkSeq( | ByVal HSLcolor As Integer, |
ByVal msDelay As Integer) As Integer |
cs | int addHslMoveToBlinkSeq( | int HSLcolor, int msDelay) |
java | int addHslMoveToBlinkSeq( | int HSLcolor, int msDelay) |
uwp | async Task<int> addHslMoveToBlinkSeq( | int HSLcolor, int msDelay) |
py | addHslMoveToBlinkSeq( | HSLcolor, msDelay) |
php | function addHslMoveToBlinkSeq( | $HSLcolor, $msDelay) |
ts | async addHslMoveToBlinkSeq( | HSLcolor: number, msDelay: number): Promise<number> |
es | async addHslMoveToBlinkSeq( | HSLcolor, msDelay) |
dnp | int addHslMoveToBlinkSeq( | int HSLcolor, int msDelay) |
cp | int addHslMoveToBlinkSeq( | int HSLcolor, int msDelay) |
cmd | YColorLed target addHslMoveToBlinkSeq | HSLcolor msDelay |
Paramètres :
HSLcolor | couleur HSL désirée à la fin de la transition |
msDelay | durée en millisecondes de la transition. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Ajoute une transition à la séquence de clignotement du module, la transition s'effectuera dans l'espace de couleur RGB
js | function addRgbMoveToBlinkSeq( | RGBcolor, msDelay) |
cpp | int addRgbMoveToBlinkSeq( | int RGBcolor, int msDelay) |
m | -(int) addRgbMoveToBlinkSeq | : (int) RGBcolor |
: (int) msDelay |
pas | LongInt addRgbMoveToBlinkSeq( | RGBcolor: LongInt, |
msDelay: LongInt): LongInt |
vb | function addRgbMoveToBlinkSeq( | ByVal RGBcolor As Integer, |
ByVal msDelay As Integer) As Integer |
cs | int addRgbMoveToBlinkSeq( | int RGBcolor, int msDelay) |
java | int addRgbMoveToBlinkSeq( | int RGBcolor, int msDelay) |
uwp | async Task<int> addRgbMoveToBlinkSeq( | int RGBcolor, int msDelay) |
py | addRgbMoveToBlinkSeq( | RGBcolor, msDelay) |
php | function addRgbMoveToBlinkSeq( | $RGBcolor, $msDelay) |
ts | async addRgbMoveToBlinkSeq( | RGBcolor: number, msDelay: number): Promise<number> |
es | async addRgbMoveToBlinkSeq( | RGBcolor, msDelay) |
dnp | int addRgbMoveToBlinkSeq( | int RGBcolor, int msDelay) |
cp | int addRgbMoveToBlinkSeq( | int RGBcolor, int msDelay) |
cmd | YColorLed target addRgbMoveToBlinkSeq | RGBcolor msDelay |
Paramètres :
RGBcolor | couleur RGB désirée à la fin de la transition |
msDelay | durée en millisecondes de la transition. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Invalide le cache.
js | function clearCache( | ) |
cpp | void clearCache( | ) |
m | -(void) clearCache |
pas | clearCache( | ) |
vb | procedure clearCache( | ) |
cs | void clearCache( | ) |
java | void clearCache( | ) |
py | clearCache( | ) |
php | function clearCache( | ) |
ts | async clearCache( | ): Promise<void> |
es | async clearCache( | ) |
Invalide le cache des valeurs courantes de la LED RGB. Force le prochain appel à une méthode get_xxx() ou loadxxx() pour charger les les données depuis le module.
Retourne un court texte décrivant de manière non-ambigüe l'instance de la LED RGB au format TYPE(NAME)=SERIAL.FUNCTIONID.
js | function describe( | ) |
cpp | string describe( | ) |
m | -(NSString*) describe |
pas | string describe( | ): string |
vb | function describe( | ) As String |
cs | string describe( | ) |
java | String describe( | ) |
py | describe( | ) |
php | function describe( | ) |
ts | async describe( | ): Promise<string> |
es | async describe( | ) |
Plus précisément, TYPE correspond au type de fonction, NAME correspond au nom utilsé lors du premier accès a la fonction, SERIAL correspond au numéro de série du module si le module est connecté, ou "unresolved" sinon, et FUNCTIONID correspond à l'identifiant matériel de la fonction si le module est connecté. Par exemple, La methode va retourner Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1 si le module est déjà connecté ou Relay(BadCustomeName.relay1)=unresolved si le module n'est pas déjà connecté. Cette methode ne declenche aucune transaction USB ou TCP et peut donc être utilisé dans un debuggeur.
Retourne :
une chaîne de caractères décrivant la LED RGB (ex: Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1)
Retourne la valeur courante de la LED RGB (pas plus de 6 caractères).
js | function get_advertisedValue( | ) |
cpp | string get_advertisedValue( | ) |
m | -(NSString*) advertisedValue |
pas | string get_advertisedValue( | ): string |
vb | function get_advertisedValue( | ) As String |
cs | string get_advertisedValue( | ) |
java | String get_advertisedValue( | ) |
uwp | async Task<string> get_advertisedValue( | ) |
py | get_advertisedValue( | ) |
php | function get_advertisedValue( | ) |
ts | async get_advertisedValue( | ): Promise<string> |
es | async get_advertisedValue( | ) |
dnp | string get_advertisedValue( | ) |
cp | string get_advertisedValue( | ) |
cmd | YColorLed target get_advertisedValue |
Retourne :
une chaîne de caractères représentant la valeur courante de la LED RGB (pas plus de 6 caractères).
En cas d'erreur, déclenche une exception ou retourne YColorLed.ADVERTISEDVALUE_INVALID.
Retourne la longueur maximum de la sequence de clignotement.
js | function get_blinkSeqMaxSize( | ) |
cpp | int get_blinkSeqMaxSize( | ) |
m | -(int) blinkSeqMaxSize |
pas | LongInt get_blinkSeqMaxSize( | ): LongInt |
vb | function get_blinkSeqMaxSize( | ) As Integer |
cs | int get_blinkSeqMaxSize( | ) |
java | int get_blinkSeqMaxSize( | ) |
uwp | async Task<int> get_blinkSeqMaxSize( | ) |
py | get_blinkSeqMaxSize( | ) |
php | function get_blinkSeqMaxSize( | ) |
ts | async get_blinkSeqMaxSize( | ): Promise<number> |
es | async get_blinkSeqMaxSize( | ) |
dnp | int get_blinkSeqMaxSize( | ) |
cp | int get_blinkSeqMaxSize( | ) |
cmd | YColorLed target get_blinkSeqMaxSize |
Retourne :
un entier représentant la longueur maximum de la sequence de clignotement
En cas d'erreur, déclenche une exception ou retourne YColorLed.BLINKSEQMAXSIZE_INVALID.
Retourne la signature de la signature de la séquence de clignotement.
js | function get_blinkSeqSignature( | ) |
cpp | int get_blinkSeqSignature( | ) |
m | -(int) blinkSeqSignature |
pas | LongInt get_blinkSeqSignature( | ): LongInt |
vb | function get_blinkSeqSignature( | ) As Integer |
cs | int get_blinkSeqSignature( | ) |
java | int get_blinkSeqSignature( | ) |
uwp | async Task<int> get_blinkSeqSignature( | ) |
py | get_blinkSeqSignature( | ) |
php | function get_blinkSeqSignature( | ) |
ts | async get_blinkSeqSignature( | ): Promise<number> |
es | async get_blinkSeqSignature( | ) |
dnp | int get_blinkSeqSignature( | ) |
cp | int get_blinkSeqSignature( | ) |
cmd | YColorLed target get_blinkSeqSignature |
Les séquences de clignotement ne pouvant pas être relues du module, ce mécanisme peut être utilisé pour détecter si une séquence spécifique est déja programmée.
Retourne :
un entier représentant la signature de la signature de la séquence de clignotement
En cas d'erreur, déclenche une exception ou retourne YColorLed.BLINKSEQSIGNATURE_INVALID.
Retourne la longueur actuelle de la sequence de clignotement.
js | function get_blinkSeqSize( | ) |
cpp | int get_blinkSeqSize( | ) |
m | -(int) blinkSeqSize |
pas | LongInt get_blinkSeqSize( | ): LongInt |
vb | function get_blinkSeqSize( | ) As Integer |
cs | int get_blinkSeqSize( | ) |
java | int get_blinkSeqSize( | ) |
uwp | async Task<int> get_blinkSeqSize( | ) |
py | get_blinkSeqSize( | ) |
php | function get_blinkSeqSize( | ) |
ts | async get_blinkSeqSize( | ): Promise<number> |
es | async get_blinkSeqSize( | ) |
dnp | int get_blinkSeqSize( | ) |
cp | int get_blinkSeqSize( | ) |
cmd | YColorLed target get_blinkSeqSize |
Retourne :
un entier représentant la longueur actuelle de la sequence de clignotement
En cas d'erreur, déclenche une exception ou retourne YColorLed.BLINKSEQSIZE_INVALID.
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation de la LED RGB.
js | function get_errorMessage( | ) |
cpp | string get_errorMessage( | ) |
m | -(NSString*) errorMessage |
pas | string get_errorMessage( | ): string |
vb | function get_errorMessage( | ) As String |
cs | string get_errorMessage( | ) |
java | String get_errorMessage( | ) |
py | get_errorMessage( | ) |
php | function get_errorMessage( | ) |
ts | get_errorMessage( | ): string |
es | get_errorMessage( | ) |
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
une chaîne de caractères correspondant au message de la dernière erreur qui s'est produit lors de l'utilisation de la LED RGB.
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation de la LED RGB.
js | function get_errorType( | ) |
cpp | YRETCODE get_errorType( | ) |
m | -(YRETCODE) errorType |
pas | YRETCODE get_errorType( | ): YRETCODE |
vb | function get_errorType( | ) As YRETCODE |
cs | YRETCODE get_errorType( | ) |
java | int get_errorType( | ) |
py | get_errorType( | ) |
php | function get_errorType( | ) |
ts | get_errorType( | ): number |
es | get_errorType( | ) |
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
un nombre correspondant au code de la dernière erreur qui s'est produit lors de l'utilisation de la LED RGB.
Retourne un identifiant global de la LED RGB au format NOM_MODULE.NOM_FONCTION.
js | function get_friendlyName( | ) |
cpp | string get_friendlyName( | ) |
m | -(NSString*) friendlyName |
cs | string get_friendlyName( | ) |
java | String get_friendlyName( | ) |
py | get_friendlyName( | ) |
php | function get_friendlyName( | ) |
ts | async get_friendlyName( | ): Promise<string> |
es | async get_friendlyName( | ) |
dnp | string get_friendlyName( | ) |
cp | string get_friendlyName( | ) |
Le chaîne retournée utilise soit les noms logiques du module et de la LED RGB si ils sont définis, soit respectivement le numéro de série du module et l'identifant matériel de la LED RGB (par exemple: MyCustomName.relay1)
Retourne :
une chaîne de caractères identifiant la LED RGB en utilisant les noms logiques (ex: MyCustomName.relay1)
En cas d'erreur, déclenche une exception ou retourne YColorLed.FRIENDLYNAME_INVALID.
Retourne un identifiant unique de type YFUN_DESCR correspondant à la fonction.
js | function get_functionDescriptor( | ) |
cpp | YFUN_DESCR get_functionDescriptor( | ) |
m | -(YFUN_DESCR) functionDescriptor |
pas | YFUN_DESCR get_functionDescriptor( | ): YFUN_DESCR |
vb | function get_functionDescriptor( | ) As YFUN_DESCR |
cs | YFUN_DESCR get_functionDescriptor( | ) |
java | String get_functionDescriptor( | ) |
py | get_functionDescriptor( | ) |
php | function get_functionDescriptor( | ) |
ts | async get_functionDescriptor( | ): Promise<string> |
es | async get_functionDescriptor( | ) |
Cet identifiant peut être utilisé pour tester si deux instance de YFunction référencent physiquement la même fonction sur le même module.
Retourne :
un identifiant de type YFUN_DESCR.
Si la fonction n'a jamais été contactée, la valeur retournée sera Y$CLASSNAME$.FUNCTIONDESCRIPTOR_INVALID
Retourne l'identifiant matériel de la LED RGB, sans référence au module.
js | function get_functionId( | ) |
cpp | string get_functionId( | ) |
m | -(NSString*) functionId |
vb | function get_functionId( | ) As String |
cs | string get_functionId( | ) |
java | String get_functionId( | ) |
py | get_functionId( | ) |
php | function get_functionId( | ) |
ts | async get_functionId( | ): Promise<string> |
es | async get_functionId( | ) |
dnp | string get_functionId( | ) |
cp | string get_functionId( | ) |
Par example relay1.
Retourne :
une chaîne de caractères identifiant la LED RGB (ex: relay1)
En cas d'erreur, déclenche une exception ou retourne YColorLed.FUNCTIONID_INVALID.
Retourne l'identifiant matériel unique de la LED RGB au format SERIAL.FUNCTIONID.
js | function get_hardwareId( | ) |
cpp | string get_hardwareId( | ) |
m | -(NSString*) hardwareId |
vb | function get_hardwareId( | ) As String |
cs | string get_hardwareId( | ) |
java | String get_hardwareId( | ) |
py | get_hardwareId( | ) |
php | function get_hardwareId( | ) |
ts | async get_hardwareId( | ): Promise<string> |
es | async get_hardwareId( | ) |
dnp | string get_hardwareId( | ) |
cp | string get_hardwareId( | ) |
L'identifiant unique est composé du numéro de série du module et de l'identifiant matériel de la LED RGB (par example RELAYLO1-123456.relay1).
Retourne :
une chaîne de caractères identifiant la LED RGB (ex: RELAYLO1-123456.relay1)
En cas d'erreur, déclenche une exception ou retourne YColorLed.HARDWAREID_INVALID.
Retourne la couleur HSL courante de la LED.
js | function get_hslColor( | ) |
cpp | int get_hslColor( | ) |
m | -(int) hslColor |
pas | LongInt get_hslColor( | ): LongInt |
vb | function get_hslColor( | ) As Integer |
cs | int get_hslColor( | ) |
java | int get_hslColor( | ) |
uwp | async Task<int> get_hslColor( | ) |
py | get_hslColor( | ) |
php | function get_hslColor( | ) |
ts | async get_hslColor( | ): Promise<number> |
es | async get_hslColor( | ) |
dnp | int get_hslColor( | ) |
cp | int get_hslColor( | ) |
cmd | YColorLed target get_hslColor |
Retourne :
un entier représentant la couleur HSL courante de la LED
En cas d'erreur, déclenche une exception ou retourne YColorLed.HSLCOLOR_INVALID.
Retourne le nom logique de la LED RGB.
js | function get_logicalName( | ) |
cpp | string get_logicalName( | ) |
m | -(NSString*) logicalName |
pas | string get_logicalName( | ): string |
vb | function get_logicalName( | ) As String |
cs | string get_logicalName( | ) |
java | String get_logicalName( | ) |
uwp | async Task<string> get_logicalName( | ) |
py | get_logicalName( | ) |
php | function get_logicalName( | ) |
ts | async get_logicalName( | ): Promise<string> |
es | async get_logicalName( | ) |
dnp | string get_logicalName( | ) |
cp | string get_logicalName( | ) |
cmd | YColorLed target get_logicalName |
Retourne :
une chaîne de caractères représentant le nom logique de la LED RGB.
En cas d'erreur, déclenche une exception ou retourne YColorLed.LOGICALNAME_INVALID.
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction.
js | function get_module( | ) |
cpp | YModule * get_module( | ) |
m | -(YModule*) module |
pas | TYModule get_module( | ): TYModule |
vb | function get_module( | ) As YModule |
cs | YModule get_module( | ) |
java | YModule get_module( | ) |
py | get_module( | ) |
php | function get_module( | ) |
ts | async get_module( | ): Promise<YModule> |
es | async get_module( | ) |
dnp | YModuleProxy get_module( | ) |
cp | YModuleProxy * get_module( | ) |
Si la fonction ne peut être trouvée sur aucun module, l'instance de YModule retournée ne sera pas joignable.
Retourne :
une instance de YModule
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction.
js | function get_module_async( | callback, context) |
Si la fonction ne peut être trouvée sur aucun module, l'instance de YModule retournée ne sera pas joignable.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la VM Javascript de Firefox, qui n'implémente pas le passage de contrôle entre threads durant les appels d'entrée/sortie bloquants.
Paramètres :
callback | fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et l'instance demandée de YModule |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
Retourne la couleur RGB courante de la LED.
js | function get_rgbColor( | ) |
cpp | int get_rgbColor( | ) |
m | -(int) rgbColor |
pas | LongInt get_rgbColor( | ): LongInt |
vb | function get_rgbColor( | ) As Integer |
cs | int get_rgbColor( | ) |
java | int get_rgbColor( | ) |
uwp | async Task<int> get_rgbColor( | ) |
py | get_rgbColor( | ) |
php | function get_rgbColor( | ) |
ts | async get_rgbColor( | ): Promise<number> |
es | async get_rgbColor( | ) |
dnp | int get_rgbColor( | ) |
cp | int get_rgbColor( | ) |
cmd | YColorLed target get_rgbColor |
Retourne :
un entier représentant la couleur RGB courante de la LED
En cas d'erreur, déclenche une exception ou retourne YColorLed.RGBCOLOR_INVALID.
Retourne la couleur configurée pour être affichage à l'allumage du module.
js | function get_rgbColorAtPowerOn( | ) |
cpp | int get_rgbColorAtPowerOn( | ) |
m | -(int) rgbColorAtPowerOn |
pas | LongInt get_rgbColorAtPowerOn( | ): LongInt |
vb | function get_rgbColorAtPowerOn( | ) As Integer |
cs | int get_rgbColorAtPowerOn( | ) |
java | int get_rgbColorAtPowerOn( | ) |
uwp | async Task<int> get_rgbColorAtPowerOn( | ) |
py | get_rgbColorAtPowerOn( | ) |
php | function get_rgbColorAtPowerOn( | ) |
ts | async get_rgbColorAtPowerOn( | ): Promise<number> |
es | async get_rgbColorAtPowerOn( | ) |
dnp | int get_rgbColorAtPowerOn( | ) |
cp | int get_rgbColorAtPowerOn( | ) |
cmd | YColorLed target get_rgbColorAtPowerOn |
Retourne :
un entier représentant la couleur configurée pour être affichage à l'allumage du module
En cas d'erreur, déclenche une exception ou retourne YColorLed.RGBCOLORATPOWERON_INVALID.
Retourne le numéro de série du module, préprogrammé en usine.
js | function get_serialNumber( | ) |
cpp | string get_serialNumber( | ) |
m | -(NSString*) serialNumber |
pas | string get_serialNumber( | ): string |
vb | function get_serialNumber( | ) As String |
cs | string get_serialNumber( | ) |
java | String get_serialNumber( | ) |
uwp | async Task<string> get_serialNumber( | ) |
py | get_serialNumber( | ) |
php | function get_serialNumber( | ) |
ts | async get_serialNumber( | ): Promise<string> |
es | async get_serialNumber( | ) |
dnp | string get_serialNumber( | ) |
cp | string get_serialNumber( | ) |
cmd | YColorLed target get_serialNumber |
Retourne :
: une chaîne de caractères représentant le numéro de série du module, préprogrammé en usine.
En cas d'erreur, déclenche une exception ou retourne YFunction.SERIALNUMBER_INVALID.
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData.
js | function get_userData( | ) |
cpp | void * get_userData( | ) |
m | -(id) userData |
pas | Tobject get_userData( | ): Tobject |
vb | function get_userData( | ) As Object |
cs | object get_userData( | ) |
java | Object get_userData( | ) |
py | get_userData( | ) |
php | function get_userData( | ) |
ts | async get_userData( | ): Promise<object|null> |
es | async get_userData( | ) |
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Retourne :
l'objet stocké précédemment par l'appelant.
Effectue une transition continue dans l'espace HSL entre la couleur courante et une nouvelle couleur.
js | function hslMove( | hsl_target, ms_duration) |
cpp | int hslMove( | int hsl_target, int ms_duration) |
m | -(int) hslMove | : (int) hsl_target : (int) ms_duration |
pas | integer hslMove( | hsl_target: LongInt, ms_duration: LongInt): integer |
vb | function hslMove( | ByVal hsl_target As Integer, |
ByVal ms_duration As Integer) As Integer |
cs | int hslMove( | int hsl_target, int ms_duration) |
java | int hslMove( | int hsl_target, int ms_duration) |
uwp | async Task<int> hslMove( | int hsl_target, int ms_duration) |
py | hslMove( | hsl_target, ms_duration) |
php | function hslMove( | $hsl_target, $ms_duration) |
ts | async hslMove( | hsl_target: number, ms_duration: number): Promise<number> |
es | async hslMove( | hsl_target, ms_duration) |
dnp | int hslMove( | int hsl_target, int ms_duration) |
cp | int hslMove( | int hsl_target, int ms_duration) |
cmd | YColorLed target hslMove | hsl_target ms_duration |
Paramètres :
hsl_target | couleur HSL désirée à la fin de la transition |
ms_duration | durée de la transition, en millisecondes |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Vérifie si le module hébergeant la LED RGB est joignable, sans déclencher d'erreur.
js | function isOnline( | ) |
cpp | bool isOnline( | ) |
m | -(BOOL) isOnline |
pas | boolean isOnline( | ): boolean |
vb | function isOnline( | ) As Boolean |
cs | bool isOnline( | ) |
java | boolean isOnline( | ) |
py | isOnline( | ) |
php | function isOnline( | ) |
ts | async isOnline( | ): Promise<boolean> |
es | async isOnline( | ) |
dnp | bool isOnline( | ) |
cp | bool isOnline( | ) |
Si les valeurs des attributs en cache de la LED RGB sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Retourne :
true si la LED RGB est joignable, false sinon
Vérifie si le module hébergeant la LED RGB est joignable, sans déclencher d'erreur.
js | function isOnline_async( | callback, context) |
Si les valeurs des attributs en cache de la LED RGB sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres :
callback | fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le résultat booléen |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
Test si la fonction est en lecture seule.
cpp | bool isReadOnly( | ) |
m | -(bool) isReadOnly |
pas | boolean isReadOnly( | ): boolean |
vb | function isReadOnly( | ) As Boolean |
cs | bool isReadOnly( | ) |
java | boolean isReadOnly( | ) |
uwp | async Task<bool> isReadOnly( | ) |
py | isReadOnly( | ) |
php | function isReadOnly( | ) |
ts | async isReadOnly( | ): Promise<boolean> |
es | async isReadOnly( | ) |
dnp | bool isReadOnly( | ) |
cp | bool isReadOnly( | ) |
cmd | YColorLed target isReadOnly |
Retourne vrais si la fonction est protégé en ecriture ou que la fontion n'est pas disponible.
Retourne :
true si la fonction est protégé en ecriture ou que la fontion n'est pas disponible
Met en cache les valeurs courantes de la LED RGB, avec une durée de validité spécifiée.
js | function load( | msValidity) |
cpp | YRETCODE load( | int msValidity) |
m | -(YRETCODE) load | : (u64) msValidity |
pas | YRETCODE load( | msValidity: u64): YRETCODE |
vb | function load( | ByVal msValidity As Long) As YRETCODE |
cs | YRETCODE load( | ulong msValidity) |
java | int load( | long msValidity) |
py | load( | msValidity) |
php | function load( | $msValidity) |
ts | async load( | msValidity: number): Promise<number> |
es | async load( | msValidity) |
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Paramètres :
msValidity | un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Retourne la valeur actuelle d'un attribut spécifique de la fonction, sous forme de texte, le plus rapidement possible mais sans passer par le cache.
js | function loadAttribute( | attrName) |
cpp | string loadAttribute( | string attrName) |
m | -(NSString*) loadAttribute | : (NSString*) attrName |
pas | string loadAttribute( | attrName: string): string |
vb | function loadAttribute( | ByVal attrName As String) As String |
cs | string loadAttribute( | string attrName) |
java | String loadAttribute( | String attrName) |
uwp | async Task<string> loadAttribute( | string attrName) |
py | loadAttribute( | attrName) |
php | function loadAttribute( | $attrName) |
ts | async loadAttribute( | attrName: string): Promise<string> |
es | async loadAttribute( | attrName) |
dnp | string loadAttribute( | string attrName) |
cp | string loadAttribute( | string attrName) |
Paramètres :
attrName | le nom de l'attribut désiré |
Retourne :
une chaîne de caractères représentant la valeur actuelle de l'attribut.
En cas d'erreur, déclenche une exception ou retourne un chaîne vide.
Met en cache les valeurs courantes de la LED RGB, avec une durée de validité spécifiée.
js | function load_async( | msValidity, callback, context) |
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres :
msValidity | un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes |
callback | fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le code d'erreur (ou YAPI.SUCCESS) |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
Désactive l'envoi de chaque changement de la valeur publiée au hub parent.
js | function muteValueCallbacks( | ) |
cpp | int muteValueCallbacks( | ) |
m | -(int) muteValueCallbacks |
pas | LongInt muteValueCallbacks( | ): LongInt |
vb | function muteValueCallbacks( | ) As Integer |
cs | int muteValueCallbacks( | ) |
java | int muteValueCallbacks( | ) |
uwp | async Task<int> muteValueCallbacks( | ) |
py | muteValueCallbacks( | ) |
php | function muteValueCallbacks( | ) |
ts | async muteValueCallbacks( | ): Promise<number> |
es | async muteValueCallbacks( | ) |
dnp | int muteValueCallbacks( | ) |
cp | int muteValueCallbacks( | ) |
cmd | YColorLed target muteValueCallbacks |
Vous pouvez utiliser cette fonction pour économiser la bande passante et le CPU sur les machines de faible puissance, ou pour éviter le déclanchement de callbacks HTTP. N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Continue l'énumération des LEDs RGB commencée à l'aide de yFirstColorLed() Attention, vous ne pouvez faire aucune supposition sur l'ordre dans lequel les LEDs RGB sont retournés.
js | function nextColorLed( | ) |
cpp | YColorLed * nextColorLed( | ) |
m | -(nullable YColorLed*) nextColorLed |
pas | TYColorLed nextColorLed( | ): TYColorLed |
vb | function nextColorLed( | ) As YColorLed |
cs | YColorLed nextColorLed( | ) |
java | YColorLed nextColorLed( | ) |
uwp | YColorLed nextColorLed( | ) |
py | nextColorLed( | ) |
php | function nextColorLed( | ) |
ts | nextColorLed( | ): YColorLed | null |
es | nextColorLed( | ) |
Si vous souhaitez retrouver une LED RGB spécifique, utilisez ColorLed.findColorLed() avec un hardwareID ou un nom logique.
Retourne :
un pointeur sur un objet YColorLed accessible en ligne, ou null lorsque l'énumération est terminée.
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée.
js | function registerValueCallback( | callback) |
cpp | int registerValueCallback( | YColorLedValueCallback callback) |
m | -(int) registerValueCallback | : (YColorLedValueCallback _Nullable) callback |
pas | LongInt registerValueCallback( | callback: TYColorLedValueCallback): LongInt |
vb | function registerValueCallback( | ByVal callback As YColorLedValueCallback) As Integer |
cs | int registerValueCallback( | ValueCallback callback) |
java | int registerValueCallback( | UpdateCallback callback) |
uwp | async Task<int> registerValueCallback( | ValueCallback callback) |
py | registerValueCallback( | callback) |
php | function registerValueCallback( | $callback) |
ts | async registerValueCallback( | callback: YColorLedValueCallback | null): Promise<number> |
es | async registerValueCallback( | callback) |
Ce callback n'est appelé que durant l'exécution de ySleep ou yHandleEvents. Cela permet à l'appelant de contrôler quand les callback peuvent se produire. Il est important d'appeler l'une de ces deux fonctions périodiquement pour garantir que les callback ne soient pas appelés trop tard. Pour désactiver un callback, il suffit d'appeler cette méthode en lui passant un pointeur nul.
Paramètres :
callback | la fonction de callback à rappeler, ou un pointeur nul. La fonction de callback doit accepter deux arguments: l'object fonction dont la valeur a changé, et la chaîne de caractère décrivant la nouvelle valeur publiée. |
efface le contenu de la sequence de clignotement.
js | function resetBlinkSeq( | ) |
cpp | int resetBlinkSeq( | ) |
m | -(int) resetBlinkSeq |
pas | LongInt resetBlinkSeq( | ): LongInt |
vb | function resetBlinkSeq( | ) As Integer |
cs | int resetBlinkSeq( | ) |
java | int resetBlinkSeq( | ) |
uwp | async Task<int> resetBlinkSeq( | ) |
py | resetBlinkSeq( | ) |
php | function resetBlinkSeq( | ) |
ts | async resetBlinkSeq( | ): Promise<number> |
es | async resetBlinkSeq( | ) |
dnp | int resetBlinkSeq( | ) |
cp | int resetBlinkSeq( | ) |
cmd | YColorLed target resetBlinkSeq |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Effectue une transition continue dans l'espace RGB entre la couleur courante et une nouvelle couleur.
js | function rgbMove( | rgb_target, ms_duration) |
cpp | int rgbMove( | int rgb_target, int ms_duration) |
m | -(int) rgbMove | : (int) rgb_target : (int) ms_duration |
pas | integer rgbMove( | rgb_target: LongInt, ms_duration: LongInt): integer |
vb | function rgbMove( | ByVal rgb_target As Integer, |
ByVal ms_duration As Integer) As Integer |
cs | int rgbMove( | int rgb_target, int ms_duration) |
java | int rgbMove( | int rgb_target, int ms_duration) |
uwp | async Task<int> rgbMove( | int rgb_target, int ms_duration) |
py | rgbMove( | rgb_target, ms_duration) |
php | function rgbMove( | $rgb_target, $ms_duration) |
ts | async rgbMove( | rgb_target: number, ms_duration: number): Promise<number> |
es | async rgbMove( | rgb_target, ms_duration) |
dnp | int rgbMove( | int rgb_target, int ms_duration) |
cp | int rgbMove( | int rgb_target, int ms_duration) |
cmd | YColorLed target rgbMove | rgb_target ms_duration |
Paramètres :
rgb_target | couleur RGB désirée à la fin de la transition |
ms_duration | durée de la transition, en millisecondes |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie la couleur courante de la LED, en utilisant une couleur HSL spécifiée.
js | function set_hslColor( | newval) |
cpp | int set_hslColor( | int newval) |
m | -(int) setHslColor | : (int) newval |
pas | integer set_hslColor( | newval: LongInt): integer |
vb | function set_hslColor( | ByVal newval As Integer) As Integer |
cs | int set_hslColor( | int newval) |
java | int set_hslColor( | int newval) |
uwp | async Task<int> set_hslColor( | int newval) |
py | set_hslColor( | newval) |
php | function set_hslColor( | $newval) |
ts | async set_hslColor( | newval: number): Promise<number> |
es | async set_hslColor( | newval) |
dnp | int set_hslColor( | int newval) |
cp | int set_hslColor( | int newval) |
cmd | YColorLed target set_hslColor | newval |
L'encodage est réalisé de la manière suivante: 0xHHSSLL.
Paramètres :
newval | un entier représentant la couleur courante de la LED, en utilisant une couleur HSL spécifiée |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie le nom logique de la LED RGB.
js | function set_logicalName( | newval) |
cpp | int set_logicalName( | string newval) |
m | -(int) setLogicalName | : (NSString*) newval |
pas | integer set_logicalName( | newval: string): integer |
vb | function set_logicalName( | ByVal newval As String) As Integer |
cs | int set_logicalName( | string newval) |
java | int set_logicalName( | String newval) |
uwp | async Task<int> set_logicalName( | string newval) |
py | set_logicalName( | newval) |
php | function set_logicalName( | $newval) |
ts | async set_logicalName( | newval: string): Promise<number> |
es | async set_logicalName( | newval) |
dnp | int set_logicalName( | string newval) |
cp | int set_logicalName( | string newval) |
cmd | YColorLed target set_logicalName | newval |
Vous pouvez utiliser yCheckLogicalName() pour vérifier si votre paramètre est valide. N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Paramètres :
newval | une chaîne de caractères représentant le nom logique de la LED RGB. |
Retourne :
YAPI.SUCCESS si l'appel se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie la couleur courante de la LED, en utilisant une couleur RGB (Rouge Vert Bleu).
js | function set_rgbColor( | newval) |
cpp | int set_rgbColor( | int newval) |
m | -(int) setRgbColor | : (int) newval |
pas | integer set_rgbColor( | newval: LongInt): integer |
vb | function set_rgbColor( | ByVal newval As Integer) As Integer |
cs | int set_rgbColor( | int newval) |
java | int set_rgbColor( | int newval) |
uwp | async Task<int> set_rgbColor( | int newval) |
py | set_rgbColor( | newval) |
php | function set_rgbColor( | $newval) |
ts | async set_rgbColor( | newval: number): Promise<number> |
es | async set_rgbColor( | newval) |
dnp | int set_rgbColor( | int newval) |
cp | int set_rgbColor( | int newval) |
cmd | YColorLed target set_rgbColor | newval |
L'encodage est réalisé de la manière suivante: 0xRRGGBB.
Paramètres :
newval | un entier représentant la couleur courante de la LED, en utilisant une couleur RGB (Rouge Vert Bleu) |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie la couleur que la LED va afficher à l'allumage du module.
js | function set_rgbColorAtPowerOn( | newval) |
cpp | int set_rgbColorAtPowerOn( | int newval) |
m | -(int) setRgbColorAtPowerOn | : (int) newval |
pas | integer set_rgbColorAtPowerOn( | newval: LongInt): integer |
vb | function set_rgbColorAtPowerOn( | ByVal newval As Integer) As Integer |
cs | int set_rgbColorAtPowerOn( | int newval) |
java | int set_rgbColorAtPowerOn( | int newval) |
uwp | async Task<int> set_rgbColorAtPowerOn( | int newval) |
py | set_rgbColorAtPowerOn( | newval) |
php | function set_rgbColorAtPowerOn( | $newval) |
ts | async set_rgbColorAtPowerOn( | newval: number): Promise<number> |
es | async set_rgbColorAtPowerOn( | newval) |
dnp | int set_rgbColorAtPowerOn( | int newval) |
cp | int set_rgbColorAtPowerOn( | int newval) |
cmd | YColorLed target set_rgbColorAtPowerOn | newval |
N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Paramètres :
newval | un entier représentant la couleur que la LED va afficher à l'allumage du module |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData.
js | function set_userData( | data) |
cpp | void set_userData( | void * data) |
m | -(void) setUserData | : (id) data |
pas | set_userData( | data: Tobject) |
vb | procedure set_userData( | ByVal data As Object) |
cs | void set_userData( | object data) |
java | void set_userData( | Object data) |
py | set_userData( | data) |
php | function set_userData( | $data) |
ts | async set_userData( | data: object|null): Promise<void> |
es | async set_userData( | data) |
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Paramètres :
data | objet quelconque à mémoriser |
Démarre l'exécution de la séquence préprogrammée de clignotement.
js | function startBlinkSeq( | ) |
cpp | int startBlinkSeq( | ) |
m | -(int) startBlinkSeq |
pas | LongInt startBlinkSeq( | ): LongInt |
vb | function startBlinkSeq( | ) As Integer |
cs | int startBlinkSeq( | ) |
java | int startBlinkSeq( | ) |
uwp | async Task<int> startBlinkSeq( | ) |
py | startBlinkSeq( | ) |
php | function startBlinkSeq( | ) |
ts | async startBlinkSeq( | ): Promise<number> |
es | async startBlinkSeq( | ) |
dnp | int startBlinkSeq( | ) |
cp | int startBlinkSeq( | ) |
cmd | YColorLed target startBlinkSeq |
La séquence va tourner en boucle jusqu'à ce qu'elle soit stoppée par stopBlinkSeq ou un changement explicite.
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Arrête l'exécution de la séquence préprogrammée de clignotement.
js | function stopBlinkSeq( | ) |
cpp | int stopBlinkSeq( | ) |
m | -(int) stopBlinkSeq |
pas | LongInt stopBlinkSeq( | ): LongInt |
vb | function stopBlinkSeq( | ) As Integer |
cs | int stopBlinkSeq( | ) |
java | int stopBlinkSeq( | ) |
uwp | async Task<int> stopBlinkSeq( | ) |
py | stopBlinkSeq( | ) |
php | function stopBlinkSeq( | ) |
ts | async stopBlinkSeq( | ): Promise<number> |
es | async stopBlinkSeq( | ) |
dnp | int stopBlinkSeq( | ) |
cp | int stopBlinkSeq( | ) |
cmd | YColorLed target stopBlinkSeq |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur. En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Réactive l'envoi de chaque changement de la valeur publiée au hub parent.
js | function unmuteValueCallbacks( | ) |
cpp | int unmuteValueCallbacks( | ) |
m | -(int) unmuteValueCallbacks |
pas | LongInt unmuteValueCallbacks( | ): LongInt |
vb | function unmuteValueCallbacks( | ) As Integer |
cs | int unmuteValueCallbacks( | ) |
java | int unmuteValueCallbacks( | ) |
uwp | async Task<int> unmuteValueCallbacks( | ) |
py | unmuteValueCallbacks( | ) |
php | function unmuteValueCallbacks( | ) |
ts | async unmuteValueCallbacks( | ): Promise<number> |
es | async unmuteValueCallbacks( | ) |
dnp | int unmuteValueCallbacks( | ) |
cp | int unmuteValueCallbacks( | ) |
cmd | YColorLed target unmuteValueCallbacks |
Cette fonction annule un précédent appel à muteValueCallbacks(). N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
js | function wait_async( | callback, context) |
ts | wait_async( | callback: Function, context: object) |
es | wait_async( | callback, context) |
La fonction callback peut donc librement utiliser des fonctions synchrones ou asynchrones, sans risquer de bloquer la machine virtuelle Javascript.
Paramètres :
callback | fonction de callback qui sera appelée dès que toutes les commandes en cours d'exécution sur le module seront terminées La fonction callback reçoit deux arguments: le contexte fourni par l'appelant et l'objet fonction concerné. |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout.
Interface pour intéragir avec les clusters de LEDs RGB, disponibles par exemple dans le Yocto-Color-V2 et le Yocto-MaxiBuzzer
La class YColorLedCluster permet de piloter un cluster de LED. Contrairement a la classe ColorLed, la classe YColorLedCluster permet de changer modifier plusieurs LEDs à la fois. Les changements de couleur peuvent être fait aussi bien en coordonnées RGB qu'en coordonnées HSL, les conversions RGB vers HSL étant faites automatiquement par le module. Ceci permet aisément d'allumer les LEDs avec une certaine teinte et d'en faire progressivement varier la saturation ou la luminosité.
Pour utiliser les fonctions décrites ici, vous devez inclure:
js | <script type='text/javascript' src='yocto_colorledcluster.js'></script> |
cpp | #include "yocto_colorledcluster.h" |
m | #import "yocto_colorledcluster.h" |
pas | uses yocto_colorledcluster; |
vb | yocto_colorledcluster.vb |
cs | yocto_colorledcluster.cs |
java | import com.yoctopuce.YoctoAPI.YColorLedCluster; |
uwp | import com.yoctopuce.YoctoAPI.YColorLedCluster; |
py | from yocto_colorledcluster import * |
php | require_once('yocto_colorledcluster.php'); |
ts | in HTML: import { YColorLedCluster } from '../../dist/esm/yocto_colorledcluster.js'; in Node.js: import { YColorLedCluster } from 'yoctolib-cjs/yocto_colorledcluster.js'; |
es | in HTML: <script src="../../lib/yocto_colorledcluster.js"></script> in node.js: require('yoctolib-es2017/yocto_colorledcluster.js'); |
dnp | import YoctoProxyAPI.YColorLedClusterProxy |
cp | #include "yocto_colorledcluster_proxy.h" |
vi | YColorLedCluster.vi |
ml | import YoctoProxyAPI.YColorLedClusterProxy |
Fonction globales |
---|
YColorLedCluster.FindColorLedCluster(func) |
Permet de retrouver un cluster de LEDs RGB d'après un identifiant donné. |
YColorLedCluster.FindColorLedClusterInContext(yctx, func) |
Permet de retrouver un cluster de LEDs RGB d'après un identifiant donné dans un Context YAPI. |
YColorLedCluster.FirstColorLedCluster() |
Commence l'énumération des clusters de LEDs RGB accessibles par la librairie. |
YColorLedCluster.FirstColorLedClusterInContext(yctx) |
Commence l'énumération des clusters de LEDs RGB accessibles par la librairie. |
YColorLedCluster.GetSimilarFunctions() |
Enumère toutes les fonctions de type ColorLedCluster disponibles sur les modules actuellement joignables par la librairie, et retourne leurs identifiants matériels uniques (hardwareId). |
Propriétés des objets YColorLedClusterProxy |
colorledcluster→ActiveLedCount [modifiable] |
Nombre de LED actuellement gérées par le module. |
colorledcluster→AdvertisedValue [lecture seule] |
Courte chaîne de caractères représentant l'état courant de la fonction. |
colorledcluster→BlinkSeqMaxCount [lecture seule] |
Nombre maximum de séquences mis à disposition par le module. |
colorledcluster→BlinkSeqMaxSize [lecture seule] |
Longueur maximum d'une sequence. |
colorledcluster→FriendlyName [lecture seule] |
Identifiant global de la fonction au format NOM_MODULE.NOM_FONCTION. |
colorledcluster→FunctionId [lecture seule] |
Identifiant matériel du cluster de LEDs RGB, sans référence au module. |
colorledcluster→HardwareId [lecture seule] |
Identifiant matériel unique de la fonction au format SERIAL.FUNCTIONID. |
colorledcluster→IsOnline [lecture seule] |
Vérifie si le module hébergeant la fonction est joignable, sans déclencher d'erreur. |
colorledcluster→LedType [modifiable] |
Type de LEDs RGB actuellement gérées par le module. |
colorledcluster→LogicalName [modifiable] |
Nom logique de la fonction. |
colorledcluster→MaxLedCount [lecture seule] |
Nombre maximum de LEDs gérables par le module. |
colorledcluster→SerialNumber [lecture seule] |
Numéro de série du module, préprogrammé en usine. |
Méthodes des objets YColorLedCluster |
colorledcluster→addHslMoveToBlinkSeq(seqIndex, hslValue, delay) |
Ajoute à une séquence une transition dans l'espace HSL. |
colorledcluster→addJumpToBlinkSeq(seqIndex, linkSeqIndex) |
Ajoute à une séquence un saut vers une autre séquence. |
colorledcluster→addMirrorToBlinkSeq(seqIndex) |
Ajoute à une séquence une fin en mirroir. |
colorledcluster→addRgbMoveToBlinkSeq(seqIndex, rgbValue, delay) |
Ajoute à une séquence une transition dans l'espace RGB. |
colorledcluster→addUnlinkToBlinkSeq(seqIndex) |
Ajoute à une séquence une commande d'arrêt. |
colorledcluster→clearCache() |
Invalide le cache. |
colorledcluster→describe() |
Retourne un court texte décrivant de manière non-ambigüe l'instance du cluster de LEDs RGB au format TYPE(NAME)=SERIAL.FUNCTIONID. |
colorledcluster→get_activeLedCount() |
Retourne le nombre de LED actuellement gérées par le module. |
colorledcluster→get_advertisedValue() |
Retourne la valeur courante du cluster de LEDs RGB (pas plus de 6 caractères). |
colorledcluster→get_blinkSeqMaxCount() |
Retourne le nombre maximum de séquences mis à disposition par le module. |
colorledcluster→get_blinkSeqMaxSize() |
Retourne la longueur maximum d'une sequence. |
colorledcluster→get_blinkSeqSignatures(seqIndex, count) |
Retourne une liste de signatures 32 bits pour les séquences de clignotement. |
colorledcluster→get_blinkSeqState(seqIndex, count) |
Retourne une liste d'entiers indiquant si les séquences sont démarrées ou pas. |
colorledcluster→get_blinkSeqStateAtPowerOn(seqIndex, count) |
Retourne une liste d'entiers indiquant l'état du flag pilotant le démarrage de la séquence à la mise sous tension du module. |
colorledcluster→get_blinkSeqStateSpeed(seqIndex, count) |
Retourne une liste d'entiers donnant la vitesse de chaque séquence. |
colorledcluster→get_errorMessage() |
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation du cluster de LEDs RGB. |
colorledcluster→get_errorType() |
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation du cluster de LEDs RGB. |
colorledcluster→get_friendlyName() |
Retourne un identifiant global du cluster de LEDs RGB au format NOM_MODULE.NOM_FONCTION. |
colorledcluster→get_functionDescriptor() |
Retourne un identifiant unique de type YFUN_DESCR correspondant à la fonction. |
colorledcluster→get_functionId() |
Retourne l'identifiant matériel du cluster de LEDs RGB, sans référence au module. |
colorledcluster→get_hardwareId() |
Retourne l'identifiant matériel unique du cluster de LEDs RGB au format SERIAL.FUNCTIONID. |
colorledcluster→get_ledType() |
Retourne le type de LEDs RGB actuellement gérées par le module. |
colorledcluster→get_linkedSeqArray(ledIndex, count) |
Retourne une liste d'index de séquence for chaque LED RGB. |
colorledcluster→get_logicalName() |
Retourne le nom logique du cluster de LEDs RGB. |
colorledcluster→get_maxLedCount() |
Retourne le nombre maximum de LEDs gérables par le module. |
colorledcluster→get_module() |
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction. |
colorledcluster→get_module_async(callback, context) |
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction. |
colorledcluster→get_rgbColorArray(ledIndex, count) |
Retourne une liste de couleurs RGB 24 bits contenant l'état des LEDs RGB, tel quel. |
colorledcluster→get_rgbColorArrayAtPowerOn(ledIndex, count) |
Retourne une liste de couleurs RGB 24 bits contenant la couleur des LEDs RGB au démarrage. |
colorledcluster→get_rgbColorBuffer(ledIndex, count) |
Retourne un objet binaire contenant l'état des LEDs RGB, tel quel. |
colorledcluster→get_serialNumber() |
Retourne le numéro de série du module, préprogrammé en usine. |
colorledcluster→get_userData() |
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData. |
colorledcluster→hslArrayOfs_move(ledIndex, hslList, delay) |
Configure une transition HSL vers une liste de couleurs HSL, pixel par pixel. |
colorledcluster→hslArray_move(hslList, delay) |
Configure une transition HSL vers une liste de couleurs HSL, pixel par pixel. |
colorledcluster→hsl_move(ledIndex, count, hslValue, delay) |
Permet de faire passer un groupe de LED adjacentes de la couleur courante à une autre, de manière continue et indépendante. |
colorledcluster→isOnline() |
Vérifie si le module hébergeant le cluster de LEDs RGB est joignable, sans déclencher d'erreur. |
colorledcluster→isOnline_async(callback, context) |
Vérifie si le module hébergeant le cluster de LEDs RGB est joignable, sans déclencher d'erreur. |
colorledcluster→isReadOnly() |
Test si la fonction est en lecture seule. |
colorledcluster→linkLedToBlinkSeq(ledIndex, count, seqIndex, offset) |
Lie un groupe de LEDs adjacentes à une séquence. |
colorledcluster→linkLedToBlinkSeqAtPowerOn(ledIndex, count, seqIndex, offset) |
Lie un groupe de LEDs adjacentes à une séquence, au démarrage du module. |
colorledcluster→linkLedToPeriodicBlinkSeq(ledIndex, count, seqIndex, periods) |
Lie un groupe de LEDs adjacentes à une séquence. |
colorledcluster→load(msValidity) |
Met en cache les valeurs courantes du cluster de LEDs RGB, avec une durée de validité spécifiée. |
colorledcluster→loadAttribute(attrName) |
Retourne la valeur actuelle d'un attribut spécifique de la fonction, sous forme de texte, le plus rapidement possible mais sans passer par le cache. |
colorledcluster→load_async(msValidity, callback, context) |
Met en cache les valeurs courantes du cluster de LEDs RGB, avec une durée de validité spécifiée. |
colorledcluster→muteValueCallbacks() |
Désactive l'envoi de chaque changement de la valeur publiée au hub parent. |
colorledcluster→nextColorLedCluster() |
Continue l'énumération des clusters de LEDs RGB commencée à l'aide de yFirstColorLedCluster() Attention, vous ne pouvez faire aucune supposition sur l'ordre dans lequel les clusters de LEDs RGB sont retournés. |
colorledcluster→registerValueCallback(callback) |
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée. |
colorledcluster→resetBlinkSeq(seqIndex) |
Stoppe l'exécution et efface le contenu d'une séquence. |
colorledcluster→rgbArrayOfs_move(ledIndex, rgbList, delay) |
Configure une transition RGB vers une liste de couleurs RGB, pixel par pixel. |
colorledcluster→rgbArray_move(rgbList, delay) |
Configure une transition RGB vers une liste de couleurs RGB, pixel par pixel. |
colorledcluster→rgb_move(ledIndex, count, rgbValue, delay) |
Permet de faire passer un groupe de LED adjacentes de la couleur courante à une autre, de manière continue et indépendante. |
colorledcluster→saveBlinkSeq(seqIndex) |
Sauve la configuration d'une séquence. |
colorledcluster→saveLedsConfigAtPowerOn() |
Sauve la configuration de démarrage des LEDs. |
colorledcluster→set_activeLedCount(newval) |
Modifie le nombre de LED actuellement gérées par le module. |
colorledcluster→set_blinkSeqSpeed(seqIndex, speed) |
Change la vitesse d'exécution d'une séquence, en pour mille. |
colorledcluster→set_blinkSeqStateAtPowerOn(seqIndex, autostart) |
Configure une séquence pour qu'elle démarre automatiquement au démarrage du module. |
colorledcluster→set_hslColor(ledIndex, count, hslValue) |
Modifie la couleur courante d'un groupe de LED consécutives en utilisant une couleur HSL . |
colorledcluster→set_hslColorArray(ledIndex, hslList) |
Envoie des couleurs HSL 24 bits (fournie sous forme d'une liste d'entiers) sur l'affichage LED HSL. |
colorledcluster→set_hslColorAtPowerOn(ledIndex, count, hslValue) |
Modifie la couleur au démarrage d'un groupe de LED consécutives en utilisant une couleur HSL. |
colorledcluster→set_hslColorBuffer(ledIndex, buff) |
Envoie un objet binaire tel quel sur l'affichage LED HSL. |
colorledcluster→set_ledType(newval) |
Modifie le type de LEDs RGB actuellement gérées par le module. |
colorledcluster→set_logicalName(newval) |
Modifie le nom logique du cluster de LEDs RGB. |
colorledcluster→set_rgbColor(ledIndex, count, rgbValue) |
Modifie la couleur courante d'un groupe de LED consécutives en utilisant une couleur RGB (Rouge Vert Bleu). |
colorledcluster→set_rgbColorArray(ledIndex, rgbList) |
Envoie des couleurs RGB 24 bits (fournie sous forme d'une liste d'entiers) sur l'affichage LED RGB. |
colorledcluster→set_rgbColorAtPowerOn(ledIndex, count, rgbValue) |
Modifie la couleur au démarrage d'un groupe de LED consécutives en utilisant une couleur RGB (Rouge Vert Bleu). |
colorledcluster→set_rgbColorBuffer(ledIndex, buff) |
Envoie un objet binaire tel quel sur l'affichage LED RGB. |
colorledcluster→set_userData(data) |
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData. |
colorledcluster→startBlinkSeq(seqIndex) |
Démarre l'exécution d'une séquence : toutes les LED liées à cette séquence vont commencer à l'exécuter en boucle. |
colorledcluster→stopBlinkSeq(seqIndex) |
Stoppe l'exécution d'une séquence. |
colorledcluster→unlinkLedFromBlinkSeq(ledIndex, count) |
Délie un groupe de LEDs adjacentes d'une séquence. |
colorledcluster→unmuteValueCallbacks() |
Réactive l'envoi de chaque changement de la valeur publiée au hub parent. |
colorledcluster→wait_async(callback, context) |
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre. |
Permet de retrouver un cluster de LEDs RGB d'après un identifiant donné.
js | function yFindColorLedCluster( | func) |
cpp | YColorLedCluster* FindColorLedCluster( | string func) |
m | +(YColorLedCluster*) FindColorLedCluster | : (NSString*) func |
pas | TYColorLedCluster yFindColorLedCluster( | func: string): TYColorLedCluster |
vb | function FindColorLedCluster( | ByVal func As String) As YColorLedCluster |
cs | static YColorLedCluster FindColorLedCluster( | string func) |
java | static YColorLedCluster FindColorLedCluster( | String func) |
uwp | static YColorLedCluster FindColorLedCluster( | string func) |
py | FindColorLedCluster( | func) |
php | function FindColorLedCluster( | $func) |
ts | static FindColorLedCluster( | func: string): YColorLedCluster |
es | static FindColorLedCluster( | func) |
dnp | static YColorLedClusterProxy FindColorLedCluster( | string func) |
cp | static YColorLedClusterProxy * FindColorLedCluster( | string func) |
L'identifiant peut être spécifié sous plusieurs formes:
Cette fonction n'exige pas que le cluster de LEDs RGB soit en ligne au moment ou elle est appelée, l'objet retourné sera néanmoins valide. Utiliser la méthode YColorLedCluster.isOnline() pour tester si le cluster de LEDs RGB est utilisable à un moment donné. En cas d'ambiguïté lorsqu'on fait une recherche par nom logique, aucune erreur ne sera notifiée: la première instance trouvée sera renvoyée. La recherche se fait d'abord par nom matériel, puis par nom logique.
Si un appel à la méthode is_online() de cet objet renvoie FAUX alors que vous êtes sûr que le module correspondant est bien branché, vérifiez que vous n'avez pas oublié d'appeler registerHub() à l'initialisation de de l'application.
Paramètres :
func | une chaîne de caractères qui référence le cluster de LEDs RGB sans ambiguïté, par exemple YRGBLED2.colorLedCluster. |
Retourne :
un objet de classe YColorLedCluster qui permet ensuite de contrôler le cluster de LEDs RGB.
Permet de retrouver un cluster de LEDs RGB d'après un identifiant donné dans un Context YAPI.
java | static YColorLedCluster FindColorLedClusterInContext( | YAPIContext yctx, |
String func) |
uwp | static YColorLedCluster FindColorLedClusterInContext( | YAPIContext yctx, |
string func) |
ts | static FindColorLedClusterInContext( | yctx: YAPIContext, func: string): YColorLedCluster |
es | static FindColorLedClusterInContext( | yctx, func) |
L'identifiant peut être spécifié sous plusieurs formes:
Cette fonction n'exige pas que le cluster de LEDs RGB soit en ligne au moment ou elle est appelée, l'objet retourné sera néanmoins valide. Utiliser la méthode YColorLedCluster.isOnline() pour tester si le cluster de LEDs RGB est utilisable à un moment donné. En cas d'ambiguïté lorsqu'on fait une recherche par nom logique, aucune erreur ne sera notifiée: la première instance trouvée sera renvoyée. La recherche se fait d'abord par nom matériel, puis par nom logique.
Paramètres :
yctx | un contexte YAPI |
func | une chaîne de caractères qui référence le cluster de LEDs RGB sans ambiguïté, par exemple YRGBLED2.colorLedCluster. |
Retourne :
un objet de classe YColorLedCluster qui permet ensuite de contrôler le cluster de LEDs RGB.
Commence l'énumération des clusters de LEDs RGB accessibles par la librairie.
js | function yFirstColorLedCluster( | ) |
cpp | YColorLedCluster * FirstColorLedCluster( | ) |
m | +(YColorLedCluster*) FirstColorLedCluster |
pas | TYColorLedCluster yFirstColorLedCluster( | ): TYColorLedCluster |
vb | function FirstColorLedCluster( | ) As YColorLedCluster |
cs | static YColorLedCluster FirstColorLedCluster( | ) |
java | static YColorLedCluster FirstColorLedCluster( | ) |
uwp | static YColorLedCluster FirstColorLedCluster( | ) |
py | FirstColorLedCluster( | ) |
php | function FirstColorLedCluster( | ) |
ts | static FirstColorLedCluster( | ): YColorLedCluster | null |
es | static FirstColorLedCluster( | ) |
Utiliser la fonction YColorLedCluster.nextColorLedCluster() pour itérer sur les autres clusters de LEDs RGB.
Retourne :
un pointeur sur un objet YColorLedCluster, correspondant au premier cluster de LEDs RGB accessible en ligne, ou null si il n'y a pas de clusters de LEDs RGB disponibles.
Commence l'énumération des clusters de LEDs RGB accessibles par la librairie.
java | static YColorLedCluster FirstColorLedClusterInContext( | YAPIContext yctx) |
uwp | static YColorLedCluster FirstColorLedClusterInContext( | YAPIContext yctx) |
ts | static FirstColorLedClusterInContext( | yctx: YAPIContext): YColorLedCluster | null |
es | static FirstColorLedClusterInContext( | yctx) |
Utiliser la fonction YColorLedCluster.nextColorLedCluster() pour itérer sur les autres clusters de LEDs RGB.
Paramètres :
yctx | un contexte YAPI. |
Retourne :
un pointeur sur un objet YColorLedCluster, correspondant au premier cluster de LEDs RGB accessible en ligne, ou null si il n'y a pas de clusters de LEDs RGB disponibles.
Enumère toutes les fonctions de type ColorLedCluster disponibles sur les modules actuellement joignables par la librairie, et retourne leurs identifiants matériels uniques (hardwareId).
dnp | static new string[] GetSimilarFunctions( | ) |
cp | static vector<string> GetSimilarFunctions( | ) |
Chaque chaîne retournée peut être passée en argument à la méthode YColorLedCluster.FindColorLedCluster pour obtenir une objet permettant d'intéragir avec le module correspondant.
Retourne :
un tableau de chaînes de caractères, contenant les identifiants matériels de chaque fonction disponible trouvée.
Nombre de LED actuellement gérées par le module.
dnp | int ActiveLedCount |
Modifiable. N'oubliez pas d'appeler la méthode saveToFlash() du module si vous désirez que le réglage soit préservé au prochain redémarrage.
Courte chaîne de caractères représentant l'état courant de la fonction.
dnp | string AdvertisedValue |
Nombre maximum de séquences mis à disposition par le module.
dnp | int BlinkSeqMaxCount |
Longueur maximum d'une sequence.
dnp | int BlinkSeqMaxSize |
Identifiant global de la fonction au format NOM_MODULE.NOM_FONCTION.
dnp | string FriendlyName |
Le chaîne retournée utilise soit les noms logiques du module et de la fonction si ils sont définis, soit respectivement le numéro de série du module et l'identifant matériel de la fonction (par exemple: MyCustomName.relay1)
Identifiant matériel du cluster de LEDs RGB, sans référence au module.
dnp | string FunctionId |
Par example relay1.
Identifiant matériel unique de la fonction au format SERIAL.FUNCTIONID.
dnp | string HardwareId |
L'identifiant unique est composé du numéro de série du module et de l'identifiant matériel de la fonction (par example RELAYLO1-123456.relay1).
Vérifie si le module hébergeant la fonction est joignable, sans déclencher d'erreur.
dnp | bool IsOnline |
Si les valeurs des attributs en cache de la fonction sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Type de LEDs RGB actuellement gérées par le module.
dnp | int LedType |
Modifiable. N'oubliez pas d'appeler la méthode saveToFlash() du module si vous désirez que le réglage soit préservé au prochain redémarrage.
Nom logique de la fonction.
dnp | string LogicalName |
Modifiable. Vous pouvez utiliser yCheckLogicalName() pour vérifier si votre paramètre est valide. N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Nombre maximum de LEDs gérables par le module.
dnp | int MaxLedCount |
Numéro de série du module, préprogrammé en usine.
dnp | string SerialNumber |
Ajoute à une séquence une transition dans l'espace HSL.
js | function addHslMoveToBlinkSeq( | seqIndex, hslValue, delay) |
cpp | int addHslMoveToBlinkSeq( | int seqIndex, int hslValue, int delay) |
m | -(int) addHslMoveToBlinkSeq | : (int) seqIndex |
: (int) hslValue | ||
: (int) delay |
pas | LongInt addHslMoveToBlinkSeq( | seqIndex: LongInt, |
hslValue: LongInt, | ||
delay: LongInt): LongInt |
vb | function addHslMoveToBlinkSeq( | ByVal seqIndex As Integer, |
ByVal hslValue As Integer, | ||
ByVal delay As Integer) As Integer |
cs | int addHslMoveToBlinkSeq( | int seqIndex, |
int hslValue, | ||
int delay) |
java | int addHslMoveToBlinkSeq( | int seqIndex, int hslValue, int delay) |
uwp | async Task<int> addHslMoveToBlinkSeq( | int seqIndex, |
int hslValue, | ||
int delay) |
py | addHslMoveToBlinkSeq( | seqIndex, hslValue, delay) |
php | function addHslMoveToBlinkSeq( | $seqIndex, $hslValue, $delay) |
ts | async addHslMoveToBlinkSeq( | seqIndex: number, hslValue: number, delay: number): Promise<number> |
es | async addHslMoveToBlinkSeq( | seqIndex, hslValue, delay) |
dnp | int addHslMoveToBlinkSeq( | int seqIndex, |
int hslValue, | ||
int delay) |
cp | int addHslMoveToBlinkSeq( | int seqIndex, |
int hslValue, | ||
int delay) |
cmd | YColorLedCluster target addHslMoveToBlinkSeq | seqIndex hslValue delay |
Une séquence est une liste de transitions qui pourra être exécutée en boucle par un groupe arbitraire de LEDs. Les séquences sont persistenteset sont sauvées dans le mémoire flash du module quand la méthode saveBlinkSeq() est appelée.
Paramètres :
seqIndex | index de la séquence. |
hslValue | couleur visée (0xHHSSLL) |
delay | durée de la transition en ms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Ajoute à une séquence un saut vers une autre séquence.
js | function addJumpToBlinkSeq( | seqIndex, linkSeqIndex) |
cpp | int addJumpToBlinkSeq( | int seqIndex, int linkSeqIndex) |
m | -(int) addJumpToBlinkSeq | : (int) seqIndex |
: (int) linkSeqIndex |
pas | LongInt addJumpToBlinkSeq( | seqIndex: LongInt, |
linkSeqIndex: LongInt): LongInt |
vb | function addJumpToBlinkSeq( | ByVal seqIndex As Integer, |
ByVal linkSeqIndex As Integer) As Integer |
cs | int addJumpToBlinkSeq( | int seqIndex, int linkSeqIndex) |
java | int addJumpToBlinkSeq( | int seqIndex, int linkSeqIndex) |
uwp | async Task<int> addJumpToBlinkSeq( | int seqIndex, int linkSeqIndex) |
py | addJumpToBlinkSeq( | seqIndex, linkSeqIndex) |
php | function addJumpToBlinkSeq( | $seqIndex, $linkSeqIndex) |
ts | async addJumpToBlinkSeq( | seqIndex: number, linkSeqIndex: number): Promise<number> |
es | async addJumpToBlinkSeq( | seqIndex, linkSeqIndex) |
dnp | int addJumpToBlinkSeq( | int seqIndex, int linkSeqIndex) |
cp | int addJumpToBlinkSeq( | int seqIndex, int linkSeqIndex) |
cmd | YColorLedCluster target addJumpToBlinkSeq | seqIndex linkSeqIndex |
Lorsqu'un pixel arrivera à ce saut, il sera automatiquement relié à la nouvelle séquence, qu'il exécutera en commençant au début.
Paramètres :
seqIndex | index de la séquence. |
linkSeqIndex | index de la séquence à enchaîner. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Ajoute à une séquence une fin en mirroir.
js | function addMirrorToBlinkSeq( | seqIndex) |
cpp | int addMirrorToBlinkSeq( | int seqIndex) |
m | -(int) addMirrorToBlinkSeq | : (int) seqIndex |
pas | LongInt addMirrorToBlinkSeq( | seqIndex: LongInt): LongInt |
vb | function addMirrorToBlinkSeq( | ByVal seqIndex As Integer) As Integer |
cs | int addMirrorToBlinkSeq( | int seqIndex) |
java | int addMirrorToBlinkSeq( | int seqIndex) |
uwp | async Task<int> addMirrorToBlinkSeq( | int seqIndex) |
py | addMirrorToBlinkSeq( | seqIndex) |
php | function addMirrorToBlinkSeq( | $seqIndex) |
ts | async addMirrorToBlinkSeq( | seqIndex: number): Promise<number> |
es | async addMirrorToBlinkSeq( | seqIndex) |
dnp | int addMirrorToBlinkSeq( | int seqIndex) |
cp | int addMirrorToBlinkSeq( | int seqIndex) |
cmd | YColorLedCluster target addMirrorToBlinkSeq | seqIndex |
Lorsque la séquence arrivera à la fin de la dernière transition, sa vitesse d'exécution sera automatiquement inversée de sorte à ce que la séquence se rejoue à l'envers, en mirroir. Lorsque la première transition sera complétée à la fin de l'exécution à l'envers, la séquence repartira à nouveau dans le sens initial.
Paramètres :
seqIndex | index de la séquence. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Ajoute à une séquence une transition dans l'espace RGB.
js | function addRgbMoveToBlinkSeq( | seqIndex, rgbValue, delay) |
cpp | int addRgbMoveToBlinkSeq( | int seqIndex, int rgbValue, int delay) |
m | -(int) addRgbMoveToBlinkSeq | : (int) seqIndex |
: (int) rgbValue | ||
: (int) delay |
pas | LongInt addRgbMoveToBlinkSeq( | seqIndex: LongInt, |
rgbValue: LongInt, | ||
delay: LongInt): LongInt |
vb | function addRgbMoveToBlinkSeq( | ByVal seqIndex As Integer, |
ByVal rgbValue As Integer, | ||
ByVal delay As Integer) As Integer |
cs | int addRgbMoveToBlinkSeq( | int seqIndex, |
int rgbValue, | ||
int delay) |
java | int addRgbMoveToBlinkSeq( | int seqIndex, int rgbValue, int delay) |
uwp | async Task<int> addRgbMoveToBlinkSeq( | int seqIndex, |
int rgbValue, | ||
int delay) |
py | addRgbMoveToBlinkSeq( | seqIndex, rgbValue, delay) |
php | function addRgbMoveToBlinkSeq( | $seqIndex, $rgbValue, $delay) |
ts | async addRgbMoveToBlinkSeq( | seqIndex: number, rgbValue: number, delay: number): Promise<number> |
es | async addRgbMoveToBlinkSeq( | seqIndex, rgbValue, delay) |
dnp | int addRgbMoveToBlinkSeq( | int seqIndex, |
int rgbValue, | ||
int delay) |
cp | int addRgbMoveToBlinkSeq( | int seqIndex, |
int rgbValue, | ||
int delay) |
cmd | YColorLedCluster target addRgbMoveToBlinkSeq | seqIndex rgbValue delay |
Une séquence est une liste de transitions qui pourra être exécutée en boucle par un groupe arbitraire de LEDs. Les séquences sont persistantes et sont sauvées dans le mémoire flash du module quand la méthode saveBlinkSeq() est applée.
Paramètres :
seqIndex | index de la séquence. |
rgbValue | couleur visée (0xRRGGBB) |
delay | durée de la transition en ms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Ajoute à une séquence une commande d'arrêt.
js | function addUnlinkToBlinkSeq( | seqIndex) |
cpp | int addUnlinkToBlinkSeq( | int seqIndex) |
m | -(int) addUnlinkToBlinkSeq | : (int) seqIndex |
pas | LongInt addUnlinkToBlinkSeq( | seqIndex: LongInt): LongInt |
vb | function addUnlinkToBlinkSeq( | ByVal seqIndex As Integer) As Integer |
cs | int addUnlinkToBlinkSeq( | int seqIndex) |
java | int addUnlinkToBlinkSeq( | int seqIndex) |
uwp | async Task<int> addUnlinkToBlinkSeq( | int seqIndex) |
py | addUnlinkToBlinkSeq( | seqIndex) |
php | function addUnlinkToBlinkSeq( | $seqIndex) |
ts | async addUnlinkToBlinkSeq( | seqIndex: number): Promise<number> |
es | async addUnlinkToBlinkSeq( | seqIndex) |
dnp | int addUnlinkToBlinkSeq( | int seqIndex) |
cp | int addUnlinkToBlinkSeq( | int seqIndex) |
cmd | YColorLedCluster target addUnlinkToBlinkSeq | seqIndex |
Lorsqu'un pixel arrivera à cette commande d'arrêt, il ne la recommencera pas en boucle mais en sera automatiquement détaché.
Paramètres :
seqIndex | index de la séquence. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Invalide le cache.
js | function clearCache( | ) |
cpp | void clearCache( | ) |
m | -(void) clearCache |
pas | clearCache( | ) |
vb | procedure clearCache( | ) |
cs | void clearCache( | ) |
java | void clearCache( | ) |
py | clearCache( | ) |
php | function clearCache( | ) |
ts | async clearCache( | ): Promise<void> |
es | async clearCache( | ) |
Invalide le cache des valeurs courantes du cluster de LEDs RGB. Force le prochain appel à une méthode get_xxx() ou loadxxx() pour charger les les données depuis le module.
Retourne un court texte décrivant de manière non-ambigüe l'instance du cluster de LEDs RGB au format TYPE(NAME)=SERIAL.FUNCTIONID.
js | function describe( | ) |
cpp | string describe( | ) |
m | -(NSString*) describe |
pas | string describe( | ): string |
vb | function describe( | ) As String |
cs | string describe( | ) |
java | String describe( | ) |
py | describe( | ) |
php | function describe( | ) |
ts | async describe( | ): Promise<string> |
es | async describe( | ) |
Plus précisément, TYPE correspond au type de fonction, NAME correspond au nom utilsé lors du premier accès a la fonction, SERIAL correspond au numéro de série du module si le module est connecté, ou "unresolved" sinon, et FUNCTIONID correspond à l'identifiant matériel de la fonction si le module est connecté. Par exemple, La methode va retourner Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1 si le module est déjà connecté ou Relay(BadCustomeName.relay1)=unresolved si le module n'est pas déjà connecté. Cette methode ne declenche aucune transaction USB ou TCP et peut donc être utilisé dans un debuggeur.
Retourne :
une chaîne de caractères décrivant le cluster de LEDs RGB (ex: Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1)
Retourne le nombre de LED actuellement gérées par le module.
js | function get_activeLedCount( | ) |
cpp | int get_activeLedCount( | ) |
m | -(int) activeLedCount |
pas | LongInt get_activeLedCount( | ): LongInt |
vb | function get_activeLedCount( | ) As Integer |
cs | int get_activeLedCount( | ) |
java | int get_activeLedCount( | ) |
uwp | async Task<int> get_activeLedCount( | ) |
py | get_activeLedCount( | ) |
php | function get_activeLedCount( | ) |
ts | async get_activeLedCount( | ): Promise<number> |
es | async get_activeLedCount( | ) |
dnp | int get_activeLedCount( | ) |
cp | int get_activeLedCount( | ) |
cmd | YColorLedCluster target get_activeLedCount |
Retourne :
un entier représentant le nombre de LED actuellement gérées par le module
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.ACTIVELEDCOUNT_INVALID.
Retourne la valeur courante du cluster de LEDs RGB (pas plus de 6 caractères).
js | function get_advertisedValue( | ) |
cpp | string get_advertisedValue( | ) |
m | -(NSString*) advertisedValue |
pas | string get_advertisedValue( | ): string |
vb | function get_advertisedValue( | ) As String |
cs | string get_advertisedValue( | ) |
java | String get_advertisedValue( | ) |
uwp | async Task<string> get_advertisedValue( | ) |
py | get_advertisedValue( | ) |
php | function get_advertisedValue( | ) |
ts | async get_advertisedValue( | ): Promise<string> |
es | async get_advertisedValue( | ) |
dnp | string get_advertisedValue( | ) |
cp | string get_advertisedValue( | ) |
cmd | YColorLedCluster target get_advertisedValue |
Retourne :
une chaîne de caractères représentant la valeur courante du cluster de LEDs RGB (pas plus de 6 caractères).
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.ADVERTISEDVALUE_INVALID.
Retourne le nombre maximum de séquences mis à disposition par le module.
js | function get_blinkSeqMaxCount( | ) |
cpp | int get_blinkSeqMaxCount( | ) |
m | -(int) blinkSeqMaxCount |
pas | LongInt get_blinkSeqMaxCount( | ): LongInt |
vb | function get_blinkSeqMaxCount( | ) As Integer |
cs | int get_blinkSeqMaxCount( | ) |
java | int get_blinkSeqMaxCount( | ) |
uwp | async Task<int> get_blinkSeqMaxCount( | ) |
py | get_blinkSeqMaxCount( | ) |
php | function get_blinkSeqMaxCount( | ) |
ts | async get_blinkSeqMaxCount( | ): Promise<number> |
es | async get_blinkSeqMaxCount( | ) |
dnp | int get_blinkSeqMaxCount( | ) |
cp | int get_blinkSeqMaxCount( | ) |
cmd | YColorLedCluster target get_blinkSeqMaxCount |
Retourne :
un entier représentant le nombre maximum de séquences mis à disposition par le module
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.BLINKSEQMAXCOUNT_INVALID.
Retourne la longueur maximum d'une sequence.
js | function get_blinkSeqMaxSize( | ) |
cpp | int get_blinkSeqMaxSize( | ) |
m | -(int) blinkSeqMaxSize |
pas | LongInt get_blinkSeqMaxSize( | ): LongInt |
vb | function get_blinkSeqMaxSize( | ) As Integer |
cs | int get_blinkSeqMaxSize( | ) |
java | int get_blinkSeqMaxSize( | ) |
uwp | async Task<int> get_blinkSeqMaxSize( | ) |
py | get_blinkSeqMaxSize( | ) |
php | function get_blinkSeqMaxSize( | ) |
ts | async get_blinkSeqMaxSize( | ): Promise<number> |
es | async get_blinkSeqMaxSize( | ) |
dnp | int get_blinkSeqMaxSize( | ) |
cp | int get_blinkSeqMaxSize( | ) |
cmd | YColorLedCluster target get_blinkSeqMaxSize |
Retourne :
un entier représentant la longueur maximum d'une sequence
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.BLINKSEQMAXSIZE_INVALID.
Retourne une liste de signatures 32 bits pour les séquences de clignotement.
js | function get_blinkSeqSignatures( | seqIndex, count) |
cpp | vector<int> get_blinkSeqSignatures( | int seqIndex, int count) |
m | -(NSMutableArray*) blinkSeqSignatures | : (int) seqIndex |
: (int) count |
pas | TLongIntArray get_blinkSeqSignatures( | seqIndex: LongInt, |
count: LongInt): TLongIntArray |
vb | function get_blinkSeqSignatures( | ByVal seqIndex As Integer, |
ByVal count As Integer) As List |
cs | List<int> get_blinkSeqSignatures( | int seqIndex, int count) |
java | ArrayList<Integer> get_blinkSeqSignatures( | int seqIndex, |
int count) |
uwp | async Task<List<int>> get_blinkSeqSignatures( | int seqIndex, int count) |
py | get_blinkSeqSignatures( | seqIndex, count) |
php | function get_blinkSeqSignatures( | $seqIndex, $count) |
ts | async get_blinkSeqSignatures( | seqIndex: number, count: number): Promise<number[] |
es | async get_blinkSeqSignatures( | seqIndex, count) |
dnp | int[] get_blinkSeqSignatures( | int seqIndex, int count) |
cp | vector<int> get_blinkSeqSignatures( | int seqIndex, int count) |
cmd | YColorLedCluster target get_blinkSeqSignatures | seqIndex count |
Les séquences de clignotement ne pouvant pas être relues du module, ce mécanisme peut être utilisé pour détecter si une séquence spécifique est déjà programmée.
Paramètres :
seqIndex | index de la première séquence qui doit être retournée |
count | nombre de séquences qui doivent être retournées |
Retourne :
une liste d'entiers 32 bits
En cas d'erreur, déclenche une exception ou retourne un tableau vide.
Retourne une liste d'entiers indiquant si les séquences sont démarrées ou pas.
js | function get_blinkSeqState( | seqIndex, count) |
cpp | vector<int> get_blinkSeqState( | int seqIndex, int count) |
m | -(NSMutableArray*) blinkSeqState | : (int) seqIndex |
: (int) count |
pas | TLongIntArray get_blinkSeqState( | seqIndex: LongInt, |
count: LongInt): TLongIntArray |
vb | function get_blinkSeqState( | ByVal seqIndex As Integer, ByVal count As Integer) As List |
cs | List<int> get_blinkSeqState( | int seqIndex, int count) |
java | ArrayList<Integer> get_blinkSeqState( | int seqIndex, int count) |
uwp | async Task<List<int>> get_blinkSeqState( | int seqIndex, int count) |
py | get_blinkSeqState( | seqIndex, count) |
php | function get_blinkSeqState( | $seqIndex, $count) |
ts | async get_blinkSeqState( | seqIndex: number, count: number): Promise<number[] |
es | async get_blinkSeqState( | seqIndex, count) |
dnp | int[] get_blinkSeqState( | int seqIndex, int count) |
cp | vector<int> get_blinkSeqState( | int seqIndex, int count) |
cmd | YColorLedCluster target get_blinkSeqState | seqIndex count |
Paramètres :
seqIndex | index de la première séquence qui doit être retournée |
count | nombre de séquences qui doivent être retournées |
Retourne :
une liste d'entiers, 0 pour les séquences arrêtées et 1 pour les séquences démarrées.
En cas d'erreur, déclenche une exception ou retourne un tableau vide.
Retourne une liste d'entiers indiquant l'état du flag pilotant le démarrage de la séquence à la mise sous tension du module.
js | function get_blinkSeqStateAtPowerOn( | seqIndex, count) |
cpp | vector<int> get_blinkSeqStateAtPowerOn( | int seqIndex, int count) |
m | -(NSMutableArray*) blinkSeqStateAtPowerOn | : (int) seqIndex |
: (int) count |
pas | TLongIntArray get_blinkSeqStateAtPowerOn( | seqIndex: LongInt, |
count: LongInt): TLongIntArray |
vb | function get_blinkSeqStateAtPowerOn( | ByVal seqIndex As Integer, |
ByVal count As Integer) As List |
cs | List<int> get_blinkSeqStateAtPowerOn( | int seqIndex, int count) |
java | ArrayList<Integer> get_blinkSeqStateAtPowerOn( | int seqIndex, |
int count) |
uwp | async Task<List<int>> get_blinkSeqStateAtPowerOn( | int seqIndex, |
int count) |
py | get_blinkSeqStateAtPowerOn( | seqIndex, count) |
php | function get_blinkSeqStateAtPowerOn( | $seqIndex, $count) |
ts | async get_blinkSeqStateAtPowerOn( | seqIndex: number, count: number): Promise<number[] |
es | async get_blinkSeqStateAtPowerOn( | seqIndex, count) |
dnp | int[] get_blinkSeqStateAtPowerOn( | int seqIndex, int count) |
cp | vector<int> get_blinkSeqStateAtPowerOn( | int seqIndex, |
int count) |
cmd | YColorLedCluster target get_blinkSeqStateAtPowerOn | seqIndex count |
Paramètres :
seqIndex | index de la première séquence qui doit être retournée |
count | nombre de séquences qui doivent être retournées |
Retourne :
une liste d'entiers, 0 pour les séquences arrêtées et 1 pour les séquences démarrées.
En cas d'erreur, déclenche une exception ou retourne un tableau vide.
Retourne une liste d'entiers donnant la vitesse de chaque séquence.
js | function get_blinkSeqStateSpeed( | seqIndex, count) |
cpp | vector<int> get_blinkSeqStateSpeed( | int seqIndex, int count) |
m | -(NSMutableArray*) blinkSeqStateSpeed | : (int) seqIndex |
: (int) count |
pas | TLongIntArray get_blinkSeqStateSpeed( | seqIndex: LongInt, |
count: LongInt): TLongIntArray |
vb | function get_blinkSeqStateSpeed( | ByVal seqIndex As Integer, |
ByVal count As Integer) As List |
cs | List<int> get_blinkSeqStateSpeed( | int seqIndex, int count) |
java | ArrayList<Integer> get_blinkSeqStateSpeed( | int seqIndex, |
int count) |
uwp | async Task<List<int>> get_blinkSeqStateSpeed( | int seqIndex, int count) |
py | get_blinkSeqStateSpeed( | seqIndex, count) |
php | function get_blinkSeqStateSpeed( | $seqIndex, $count) |
ts | async get_blinkSeqStateSpeed( | seqIndex: number, count: number): Promise<number[] |
es | async get_blinkSeqStateSpeed( | seqIndex, count) |
dnp | int[] get_blinkSeqStateSpeed( | int seqIndex, int count) |
cp | vector<int> get_blinkSeqStateSpeed( | int seqIndex, int count) |
cmd | YColorLedCluster target get_blinkSeqStateSpeed | seqIndex count |
Paramètres :
seqIndex | index de la première séquence dont le vitesse doit être retournée |
count | nombre de séquences à traiter |
Retourne :
une liste d'entiers, 0 pour les séquences arrêtées et 1 pour les séquences démarrées.
En cas d'erreur, déclenche une exception ou retourne un tableau vide.
Retourne le message correspondant à la dernière erreur survenue lors de l'utilisation du cluster de LEDs RGB.
js | function get_errorMessage( | ) |
cpp | string get_errorMessage( | ) |
m | -(NSString*) errorMessage |
pas | string get_errorMessage( | ): string |
vb | function get_errorMessage( | ) As String |
cs | string get_errorMessage( | ) |
java | String get_errorMessage( | ) |
py | get_errorMessage( | ) |
php | function get_errorMessage( | ) |
ts | get_errorMessage( | ): string |
es | get_errorMessage( | ) |
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
une chaîne de caractères correspondant au message de la dernière erreur qui s'est produit lors de l'utilisation du cluster de LEDs RGB.
Retourne le code d'erreur correspondant à la dernière erreur survenue lors de l'utilisation du cluster de LEDs RGB.
js | function get_errorType( | ) |
cpp | YRETCODE get_errorType( | ) |
m | -(YRETCODE) errorType |
pas | YRETCODE get_errorType( | ): YRETCODE |
vb | function get_errorType( | ) As YRETCODE |
cs | YRETCODE get_errorType( | ) |
java | int get_errorType( | ) |
py | get_errorType( | ) |
php | function get_errorType( | ) |
ts | get_errorType( | ): number |
es | get_errorType( | ) |
Cette méthode est principalement utile lorsque la librairie Yoctopuce est utilisée en désactivant la gestion des exceptions.
Retourne :
un nombre correspondant au code de la dernière erreur qui s'est produit lors de l'utilisation du cluster de LEDs RGB.
Retourne un identifiant global du cluster de LEDs RGB au format NOM_MODULE.NOM_FONCTION.
js | function get_friendlyName( | ) |
cpp | string get_friendlyName( | ) |
m | -(NSString*) friendlyName |
cs | string get_friendlyName( | ) |
java | String get_friendlyName( | ) |
py | get_friendlyName( | ) |
php | function get_friendlyName( | ) |
ts | async get_friendlyName( | ): Promise<string> |
es | async get_friendlyName( | ) |
dnp | string get_friendlyName( | ) |
cp | string get_friendlyName( | ) |
Le chaîne retournée utilise soit les noms logiques du module et du cluster de LEDs RGB si ils sont définis, soit respectivement le numéro de série du module et l'identifant matériel du cluster de LEDs RGB (par exemple: MyCustomName.relay1)
Retourne :
une chaîne de caractères identifiant le cluster de LEDs RGB en utilisant les noms logiques (ex: MyCustomName.relay1)
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.FRIENDLYNAME_INVALID.
Retourne un identifiant unique de type YFUN_DESCR correspondant à la fonction.
js | function get_functionDescriptor( | ) |
cpp | YFUN_DESCR get_functionDescriptor( | ) |
m | -(YFUN_DESCR) functionDescriptor |
pas | YFUN_DESCR get_functionDescriptor( | ): YFUN_DESCR |
vb | function get_functionDescriptor( | ) As YFUN_DESCR |
cs | YFUN_DESCR get_functionDescriptor( | ) |
java | String get_functionDescriptor( | ) |
py | get_functionDescriptor( | ) |
php | function get_functionDescriptor( | ) |
ts | async get_functionDescriptor( | ): Promise<string> |
es | async get_functionDescriptor( | ) |
Cet identifiant peut être utilisé pour tester si deux instance de YFunction référencent physiquement la même fonction sur le même module.
Retourne :
un identifiant de type YFUN_DESCR.
Si la fonction n'a jamais été contactée, la valeur retournée sera Y$CLASSNAME$.FUNCTIONDESCRIPTOR_INVALID
Retourne l'identifiant matériel du cluster de LEDs RGB, sans référence au module.
js | function get_functionId( | ) |
cpp | string get_functionId( | ) |
m | -(NSString*) functionId |
vb | function get_functionId( | ) As String |
cs | string get_functionId( | ) |
java | String get_functionId( | ) |
py | get_functionId( | ) |
php | function get_functionId( | ) |
ts | async get_functionId( | ): Promise<string> |
es | async get_functionId( | ) |
dnp | string get_functionId( | ) |
cp | string get_functionId( | ) |
Par example relay1.
Retourne :
une chaîne de caractères identifiant le cluster de LEDs RGB (ex: relay1)
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.FUNCTIONID_INVALID.
Retourne l'identifiant matériel unique du cluster de LEDs RGB au format SERIAL.FUNCTIONID.
js | function get_hardwareId( | ) |
cpp | string get_hardwareId( | ) |
m | -(NSString*) hardwareId |
vb | function get_hardwareId( | ) As String |
cs | string get_hardwareId( | ) |
java | String get_hardwareId( | ) |
py | get_hardwareId( | ) |
php | function get_hardwareId( | ) |
ts | async get_hardwareId( | ): Promise<string> |
es | async get_hardwareId( | ) |
dnp | string get_hardwareId( | ) |
cp | string get_hardwareId( | ) |
L'identifiant unique est composé du numéro de série du module et de l'identifiant matériel du cluster de LEDs RGB (par example RELAYLO1-123456.relay1).
Retourne :
une chaîne de caractères identifiant le cluster de LEDs RGB (ex: RELAYLO1-123456.relay1)
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.HARDWAREID_INVALID.
Retourne le type de LEDs RGB actuellement gérées par le module.
js | function get_ledType( | ) |
cpp | Y_LEDTYPE_enum get_ledType( | ) |
m | -(Y_LEDTYPE_enum) ledType |
pas | Integer get_ledType( | ): Integer |
vb | function get_ledType( | ) As Integer |
cs | int get_ledType( | ) |
java | int get_ledType( | ) |
uwp | async Task<int> get_ledType( | ) |
py | get_ledType( | ) |
php | function get_ledType( | ) |
ts | async get_ledType( | ): Promise<YColorLedCluster_LedType> |
es | async get_ledType( | ) |
dnp | int get_ledType( | ) |
cp | int get_ledType( | ) |
cmd | YColorLedCluster target get_ledType |
Retourne :
soit YColorLedCluster.LEDTYPE_RGB, soit YColorLedCluster.LEDTYPE_RGBW, selon le type de LEDs RGB actuellement gérées par le module
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.LEDTYPE_INVALID.
Retourne une liste d'index de séquence for chaque LED RGB.
js | function get_linkedSeqArray( | ledIndex, count) |
cpp | vector<int> get_linkedSeqArray( | int ledIndex, int count) |
m | -(NSMutableArray*) linkedSeqArray | : (int) ledIndex |
: (int) count |
pas | TLongIntArray get_linkedSeqArray( | ledIndex: LongInt, |
count: LongInt): TLongIntArray |
vb | function get_linkedSeqArray( | ByVal ledIndex As Integer, ByVal count As Integer) As List |
cs | List<int> get_linkedSeqArray( | int ledIndex, int count) |
java | ArrayList<Integer> get_linkedSeqArray( | int ledIndex, int count) |
uwp | async Task<List<int>> get_linkedSeqArray( | int ledIndex, int count) |
py | get_linkedSeqArray( | ledIndex, count) |
php | function get_linkedSeqArray( | $ledIndex, $count) |
ts | async get_linkedSeqArray( | ledIndex: number, count: number): Promise<number[] |
es | async get_linkedSeqArray( | ledIndex, count) |
dnp | int[] get_linkedSeqArray( | int ledIndex, int count) |
cp | vector<int> get_linkedSeqArray( | int ledIndex, int count) |
cmd | YColorLedCluster target get_linkedSeqArray | ledIndex count |
Le premier entier correspond à l'index de la première LED, l'entier suivant à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être retournée |
count | nombre de LEDs qui doivent être retournées |
Retourne :
une liste d'entiers correspondant à des index de séquence.
En cas d'erreur, déclenche une exception ou retourne un tableau vide.
Retourne le nom logique du cluster de LEDs RGB.
js | function get_logicalName( | ) |
cpp | string get_logicalName( | ) |
m | -(NSString*) logicalName |
pas | string get_logicalName( | ): string |
vb | function get_logicalName( | ) As String |
cs | string get_logicalName( | ) |
java | String get_logicalName( | ) |
uwp | async Task<string> get_logicalName( | ) |
py | get_logicalName( | ) |
php | function get_logicalName( | ) |
ts | async get_logicalName( | ): Promise<string> |
es | async get_logicalName( | ) |
dnp | string get_logicalName( | ) |
cp | string get_logicalName( | ) |
cmd | YColorLedCluster target get_logicalName |
Retourne :
une chaîne de caractères représentant le nom logique du cluster de LEDs RGB.
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.LOGICALNAME_INVALID.
Retourne le nombre maximum de LEDs gérables par le module.
js | function get_maxLedCount( | ) |
cpp | int get_maxLedCount( | ) |
m | -(int) maxLedCount |
pas | LongInt get_maxLedCount( | ): LongInt |
vb | function get_maxLedCount( | ) As Integer |
cs | int get_maxLedCount( | ) |
java | int get_maxLedCount( | ) |
uwp | async Task<int> get_maxLedCount( | ) |
py | get_maxLedCount( | ) |
php | function get_maxLedCount( | ) |
ts | async get_maxLedCount( | ): Promise<number> |
es | async get_maxLedCount( | ) |
dnp | int get_maxLedCount( | ) |
cp | int get_maxLedCount( | ) |
cmd | YColorLedCluster target get_maxLedCount |
Retourne :
un entier représentant le nombre maximum de LEDs gérables par le module
En cas d'erreur, déclenche une exception ou retourne YColorLedCluster.MAXLEDCOUNT_INVALID.
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction.
js | function get_module( | ) |
cpp | YModule * get_module( | ) |
m | -(YModule*) module |
pas | TYModule get_module( | ): TYModule |
vb | function get_module( | ) As YModule |
cs | YModule get_module( | ) |
java | YModule get_module( | ) |
py | get_module( | ) |
php | function get_module( | ) |
ts | async get_module( | ): Promise<YModule> |
es | async get_module( | ) |
dnp | YModuleProxy get_module( | ) |
cp | YModuleProxy * get_module( | ) |
Si la fonction ne peut être trouvée sur aucun module, l'instance de YModule retournée ne sera pas joignable.
Retourne :
une instance de YModule
Retourne l'objet YModule correspondant au module Yoctopuce qui héberge la fonction.
js | function get_module_async( | callback, context) |
Si la fonction ne peut être trouvée sur aucun module, l'instance de YModule retournée ne sera pas joignable.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la VM Javascript de Firefox, qui n'implémente pas le passage de contrôle entre threads durant les appels d'entrée/sortie bloquants.
Paramètres :
callback | fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et l'instance demandée de YModule |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
Retourne une liste de couleurs RGB 24 bits contenant l'état des LEDs RGB, tel quel.
js | function get_rgbColorArray( | ledIndex, count) |
cpp | vector<int> get_rgbColorArray( | int ledIndex, int count) |
m | -(NSMutableArray*) rgbColorArray | : (int) ledIndex |
: (int) count |
pas | TLongIntArray get_rgbColorArray( | ledIndex: LongInt, |
count: LongInt): TLongIntArray |
vb | function get_rgbColorArray( | ByVal ledIndex As Integer, ByVal count As Integer) As List |
cs | List<int> get_rgbColorArray( | int ledIndex, int count) |
java | ArrayList<Integer> get_rgbColorArray( | int ledIndex, int count) |
uwp | async Task<List<int>> get_rgbColorArray( | int ledIndex, int count) |
py | get_rgbColorArray( | ledIndex, count) |
php | function get_rgbColorArray( | $ledIndex, $count) |
ts | async get_rgbColorArray( | ledIndex: number, count: number): Promise<number[] |
es | async get_rgbColorArray( | ledIndex, count) |
dnp | int[] get_rgbColorArray( | int ledIndex, int count) |
cp | vector<int> get_rgbColorArray( | int ledIndex, int count) |
cmd | YColorLedCluster target get_rgbColorArray | ledIndex count |
Le premier entier correspond à la couleur RGB de la première LED, l'entier suivant à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être retournée |
count | nombre de LEDs qui doivent être retournées |
Retourne :
une liste de couleurs 24bit avec les composantes RGB des LEDs choisies, au format 0xRRGGBB.
En cas d'erreur, déclenche une exception ou retourne un tableau vide.
Retourne une liste de couleurs RGB 24 bits contenant la couleur des LEDs RGB au démarrage.
js | function get_rgbColorArrayAtPowerOn( | ledIndex, count) |
cpp | vector<int> get_rgbColorArrayAtPowerOn( | int ledIndex, int count) |
m | -(NSMutableArray*) rgbColorArrayAtPowerOn | : (int) ledIndex |
: (int) count |
pas | TLongIntArray get_rgbColorArrayAtPowerOn( | ledIndex: LongInt, |
count: LongInt): TLongIntArray |
vb | function get_rgbColorArrayAtPowerOn( | ByVal ledIndex As Integer, |
ByVal count As Integer) As List |
cs | List<int> get_rgbColorArrayAtPowerOn( | int ledIndex, int count) |
java | ArrayList<Integer> get_rgbColorArrayAtPowerOn( | int ledIndex, |
int count) |
uwp | async Task<List<int>> get_rgbColorArrayAtPowerOn( | int ledIndex, |
int count) |
py | get_rgbColorArrayAtPowerOn( | ledIndex, count) |
php | function get_rgbColorArrayAtPowerOn( | $ledIndex, $count) |
ts | async get_rgbColorArrayAtPowerOn( | ledIndex: number, count: number): Promise<number[] |
es | async get_rgbColorArrayAtPowerOn( | ledIndex, count) |
dnp | int[] get_rgbColorArrayAtPowerOn( | int ledIndex, int count) |
cp | vector<int> get_rgbColorArrayAtPowerOn( | int ledIndex, |
int count) |
cmd | YColorLedCluster target get_rgbColorArrayAtPowerOn | ledIndex count |
Le premier entier correspond à la couleur RGB de démarrage de la première LED, l'entier suivant à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être retournée |
count | nombre de LEDs qui doivent être retournées |
Retourne :
une liste de couleurs 24bit avec les composantes RGB des LEDs choisies, au format 0xRRGGBB.
En cas d'erreur, déclenche une exception ou retourne un tableau vide.
Retourne un objet binaire contenant l'état des LEDs RGB, tel quel.
js | function get_rgbColorBuffer( | ledIndex, count) |
cpp | string get_rgbColorBuffer( | int ledIndex, int count) |
m | -(NSMutableData*) rgbColorBuffer | : (int) ledIndex |
: (int) count |
pas | TByteArray get_rgbColorBuffer( | ledIndex: LongInt, |
count: LongInt): TByteArray |
vb | function get_rgbColorBuffer( | ByVal ledIndex As Integer, ByVal count As Integer) As Byte |
cs | byte[] get_rgbColorBuffer( | int ledIndex, int count) |
java | byte[] get_rgbColorBuffer( | int ledIndex, int count) |
uwp | async Task<byte[]> get_rgbColorBuffer( | int ledIndex, int count) |
py | get_rgbColorBuffer( | ledIndex, count) |
php | function get_rgbColorBuffer( | $ledIndex, $count) |
ts | async get_rgbColorBuffer( | ledIndex: number, count: number): Promise<Uint8Array> |
es | async get_rgbColorBuffer( | ledIndex, count) |
dnp | byte[] get_rgbColorBuffer( | int ledIndex, int count) |
cp | string get_rgbColorBuffer( | int ledIndex, int count) |
cmd | YColorLedCluster target get_rgbColorBuffer | ledIndex count |
Les trois premiers octets correspondent aux composantes RGB de la première LED choisie, les trois octets suivants à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être retournée |
count | nombre de LEDs qui doivent être retournées |
Retourne :
un objet binaire avec les composantes RGB des LEDs choisies.
En cas d'erreur, déclenche une exception ou retourne un objet binaire vide.
Retourne le numéro de série du module, préprogrammé en usine.
js | function get_serialNumber( | ) |
cpp | string get_serialNumber( | ) |
m | -(NSString*) serialNumber |
pas | string get_serialNumber( | ): string |
vb | function get_serialNumber( | ) As String |
cs | string get_serialNumber( | ) |
java | String get_serialNumber( | ) |
uwp | async Task<string> get_serialNumber( | ) |
py | get_serialNumber( | ) |
php | function get_serialNumber( | ) |
ts | async get_serialNumber( | ): Promise<string> |
es | async get_serialNumber( | ) |
dnp | string get_serialNumber( | ) |
cp | string get_serialNumber( | ) |
cmd | YColorLedCluster target get_serialNumber |
Retourne :
: une chaîne de caractères représentant le numéro de série du module, préprogrammé en usine.
En cas d'erreur, déclenche une exception ou retourne YFunction.SERIALNUMBER_INVALID.
Retourne le contenu de l'attribut userData, précédemment stocké à l'aide de la méthode set_userData.
js | function get_userData( | ) |
cpp | void * get_userData( | ) |
m | -(id) userData |
pas | Tobject get_userData( | ): Tobject |
vb | function get_userData( | ) As Object |
cs | object get_userData( | ) |
java | Object get_userData( | ) |
py | get_userData( | ) |
php | function get_userData( | ) |
ts | async get_userData( | ): Promise<object|null> |
es | async get_userData( | ) |
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Retourne :
l'objet stocké précédemment par l'appelant.
Configure une transition HSL vers une liste de couleurs HSL, pixel par pixel.
js | function hslArrayOfs_move( | ledIndex, hslList, delay) |
cpp | int hslArrayOfs_move( | int ledIndex, vector<int> hslList, int delay) |
m | -(int) hslArrayOfs_move | : (int) ledIndex |
: (NSMutableArray*) hslList | ||
: (int) delay |
pas | LongInt hslArrayOfs_move( | ledIndex: LongInt, |
hslList: TLongIntArray, | ||
delay: LongInt): LongInt |
vb | procedure hslArrayOfs_move( | ByVal ledIndex As Integer, |
ByVal hslList As List(Of) |
cs | int hslArrayOfs_move( | int ledIndex, |
List<int> hslList, | ||
int delay) |
java | int hslArrayOfs_move( | int ledIndex, |
ArrayList<Integer> hslList, | ||
int delay) |
uwp | async Task<int> hslArrayOfs_move( | int ledIndex, |
List<int> hslList, | ||
int delay) |
py | hslArrayOfs_move( | ledIndex, hslList, delay) |
php | function hslArrayOfs_move( | $ledIndex, $hslList, $delay) |
ts | async hslArrayOfs_move( | ledIndex: number, hslList: number[], delay: number): Promise<number> |
es | async hslArrayOfs_move( | ledIndex, hslList, delay) |
dnp | int hslArrayOfs_move( | int ledIndex, int[] hslList, int delay) |
cp | int hslArrayOfs_move( | int ledIndex, |
vector<int> hslList, | ||
int delay) |
cmd | YColorLedCluster target hslArrayOfs_move | ledIndex hslList delay |
Le premier entier correspond à la couleur RGB finale pour la première LED, l'entier suivant à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être modifiée |
hslList | la liste de valeurs HSL (24 bits) finales désirées, au format 0xHHSSLL |
delay | durée de la transition en ms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Configure une transition HSL vers une liste de couleurs HSL, pixel par pixel.
js | function hslArray_move( | hslList, delay) |
cpp | int hslArray_move( | vector<int> hslList, int delay) |
m | -(int) hslArray_move | : (NSMutableArray*) hslList : (int) delay |
pas | LongInt hslArray_move( | hslList: TLongIntArray, delay: LongInt): LongInt |
vb | procedure hslArray_move( | ByVal hslList As List(Of) |
cs | int hslArray_move( | List<int> hslList, int delay) |
java | int hslArray_move( | ArrayList<Integer> hslList, int delay) |
uwp | async Task<int> hslArray_move( | List<int> hslList, int delay) |
py | hslArray_move( | hslList, delay) |
php | function hslArray_move( | $hslList, $delay) |
ts | async hslArray_move( | hslList: number[], delay: number): Promise<number> |
es | async hslArray_move( | hslList, delay) |
dnp | int hslArray_move( | int[] hslList, int delay) |
cp | int hslArray_move( | vector<int> hslList, int delay) |
cmd | YColorLedCluster target hslArray_move | hslList delay |
Le premier entier correspond à la couleur RGB finale pour la première LED, l'entier suivant à la LED suivante, etc.
Paramètres :
hslList | la liste de valeurs HSL (24 bits) finales désirées, au format 0xHHSSLL |
delay | durée de la transition en ms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Permet de faire passer un groupe de LED adjacentes de la couleur courante à une autre, de manière continue et indépendante.
js | function hsl_move( | ledIndex, count, hslValue, delay) |
cpp | int hsl_move( | int ledIndex, int count, int hslValue, int delay) |
m | -(int) hsl_move | : (int) ledIndex |
: (int) count | ||
: (int) hslValue | ||
: (int) delay |
pas | LongInt hsl_move( | ledIndex: LongInt, |
count: LongInt, | ||
hslValue: LongInt, | ||
delay: LongInt): LongInt |
vb | function hsl_move( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal hslValue As Integer, | ||
ByVal delay As Integer) As Integer |
cs | int hsl_move( | int ledIndex, int count, int hslValue, int delay) |
java | int hsl_move( | int ledIndex, int count, int hslValue, int delay) |
uwp | async Task<int> hsl_move( | int ledIndex, |
int count, | ||
int hslValue, | ||
int delay) |
py | hsl_move( | ledIndex, count, hslValue, delay) |
php | function hsl_move( | $ledIndex, $count, $hslValue, $delay) |
ts | async hsl_move( | ledIndex: number, count: number, hslValue: number, delay: number): Promise<number> |
es | async hsl_move( | ledIndex, count, hslValue, delay) |
dnp | int hsl_move( | int ledIndex, int count, int hslValue, int delay) |
cp | int hsl_move( | int ledIndex, int count, int hslValue, int delay) |
cmd | YColorLedCluster target hsl_move | ledIndex count hslValue delay |
La transition se fait dans l'espace HSL. En HSL, la teinte étant une valeur circulaire (0..360°) il y a toujours deux manières d'opérer la transition: en augmentant ou en diminuant le teinte. Le module optera pour la transition passant par le chemin le plus court. dans le cas d'une différence d'exactement 180°, il optera pour la transition qui augmente la valeur de la teinte.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
hslValue | nouvelle couleur (0xHHSSLL) |
delay | durée de la transition enms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Vérifie si le module hébergeant le cluster de LEDs RGB est joignable, sans déclencher d'erreur.
js | function isOnline( | ) |
cpp | bool isOnline( | ) |
m | -(BOOL) isOnline |
pas | boolean isOnline( | ): boolean |
vb | function isOnline( | ) As Boolean |
cs | bool isOnline( | ) |
java | boolean isOnline( | ) |
py | isOnline( | ) |
php | function isOnline( | ) |
ts | async isOnline( | ): Promise<boolean> |
es | async isOnline( | ) |
dnp | bool isOnline( | ) |
cp | bool isOnline( | ) |
Si les valeurs des attributs en cache du cluster de LEDs RGB sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Retourne :
true si le cluster de LEDs RGB est joignable, false sinon
Vérifie si le module hébergeant le cluster de LEDs RGB est joignable, sans déclencher d'erreur.
js | function isOnline_async( | callback, context) |
Si les valeurs des attributs en cache du cluster de LEDs RGB sont valides au moment de l'appel, le module est considéré joignable. Cette fonction ne cause en aucun cas d'exception, quelle que soit l'erreur qui pourrait se produire lors de la vérification de joignabilité.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres :
callback | fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le résultat booléen |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
Test si la fonction est en lecture seule.
cpp | bool isReadOnly( | ) |
m | -(bool) isReadOnly |
pas | boolean isReadOnly( | ): boolean |
vb | function isReadOnly( | ) As Boolean |
cs | bool isReadOnly( | ) |
java | boolean isReadOnly( | ) |
uwp | async Task<bool> isReadOnly( | ) |
py | isReadOnly( | ) |
php | function isReadOnly( | ) |
ts | async isReadOnly( | ): Promise<boolean> |
es | async isReadOnly( | ) |
dnp | bool isReadOnly( | ) |
cp | bool isReadOnly( | ) |
cmd | YColorLedCluster target isReadOnly |
Retourne vrais si la fonction est protégé en ecriture ou que la fontion n'est pas disponible.
Retourne :
true si la fonction est protégé en ecriture ou que la fontion n'est pas disponible
Lie un groupe de LEDs adjacentes à une séquence.
js | function linkLedToBlinkSeq( | ledIndex, count, seqIndex, offset) |
cpp | int linkLedToBlinkSeq( | int ledIndex, int count, int seqIndex, int offset) |
m | -(int) linkLedToBlinkSeq | : (int) ledIndex |
: (int) count | ||
: (int) seqIndex | ||
: (int) offset |
pas | LongInt linkLedToBlinkSeq( | ledIndex: LongInt, |
count: LongInt, | ||
seqIndex: LongInt, | ||
offset: LongInt): LongInt |
vb | function linkLedToBlinkSeq( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal seqIndex As Integer, | ||
ByVal offset As Integer) As Integer |
cs | int linkLedToBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
java | int linkLedToBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
uwp | async Task<int> linkLedToBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
py | linkLedToBlinkSeq( | ledIndex, count, seqIndex, offset) |
php | function linkLedToBlinkSeq( | $ledIndex, $count, $seqIndex, $offset) |
ts | async linkLedToBlinkSeq( | ledIndex: number, count: number, seqIndex: number, offset: number): Promise<number> |
es | async linkLedToBlinkSeq( | ledIndex, count, seqIndex, offset) |
dnp | int linkLedToBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
cp | int linkLedToBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
cmd | YColorLedCluster target linkLedToBlinkSeq | ledIndex count seqIndex offset |
Ces LEDs commenceront à exécuter la séquence dès que son exécution sera lancé à l'aide de startBlinkSeq. Il est possible d'induire un décalage dans l'exécution à l'aide du paramètre offset. On peut ainsi créer plusieurs groupes de LEDs qui exécutent la même séquence mais de manière décalée. Une LED ne peut être affectée qu'à une seule séquence à la fois.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
seqIndex | index de la séquence. |
offset | décalage dans l'exécution de la séquence en ms |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Lie un groupe de LEDs adjacentes à une séquence, au démarrage du module.
js | function linkLedToBlinkSeqAtPowerOn( | ledIndex, count, seqIndex, offset) |
cpp | int linkLedToBlinkSeqAtPowerOn( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
m | -(int) linkLedToBlinkSeqAtPowerOn | : (int) ledIndex |
: (int) count | ||
: (int) seqIndex | ||
: (int) offset |
pas | LongInt linkLedToBlinkSeqAtPowerOn( | ledIndex: LongInt, |
count: LongInt, | ||
seqIndex: LongInt, | ||
offset: LongInt): LongInt |
vb | function linkLedToBlinkSeqAtPowerOn( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal seqIndex As Integer, | ||
ByVal offset As Integer) As Integer |
cs | int linkLedToBlinkSeqAtPowerOn( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
java | int linkLedToBlinkSeqAtPowerOn( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
uwp | async Task<int> linkLedToBlinkSeqAtPowerOn( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
py | linkLedToBlinkSeqAtPowerOn( | ledIndex, count, seqIndex, offset) |
php | function linkLedToBlinkSeqAtPowerOn( | $ledIndex, $count, $seqIndex, $offset) |
ts | async linkLedToBlinkSeqAtPowerOn( | ledIndex: number, count: number, seqIndex: number, offset: number): Promise<number> |
es | async linkLedToBlinkSeqAtPowerOn( | ledIndex, count, seqIndex, offset) |
dnp | int linkLedToBlinkSeqAtPowerOn( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
cp | int linkLedToBlinkSeqAtPowerOn( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int offset) |
cmd | YColorLedCluster target linkLedToBlinkSeqAtPowerOn | ledIndex count seqIndex offset |
Ne pas oublier de configurer le démarrage automatique de la séquence et d'appeler saveLedsConfigAtPowerOn(). Il est possible d'induire un décalage dans l'exécution à l'aide du paramètre offset. On peut ainsi créer plusieurs groupes de LEDs qui exécutent la même séquence mais de manière décalée. Une LED ne peut être affectée qu'à une seule séquence à la fois.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
seqIndex | index de la séquence. |
offset | décalage dans l'exécution de la séquence en ms |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Lie un groupe de LEDs adjacentes à une séquence.
js | function linkLedToPeriodicBlinkSeq( | ledIndex, count, seqIndex, periods) |
cpp | int linkLedToPeriodicBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int periods) |
m | -(int) linkLedToPeriodicBlinkSeq | : (int) ledIndex |
: (int) count | ||
: (int) seqIndex | ||
: (int) periods |
pas | LongInt linkLedToPeriodicBlinkSeq( | ledIndex: LongInt, |
count: LongInt, | ||
seqIndex: LongInt, | ||
periods: LongInt): LongInt |
vb | function linkLedToPeriodicBlinkSeq( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal seqIndex As Integer, | ||
ByVal periods As Integer) As Integer |
cs | int linkLedToPeriodicBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int periods) |
java | int linkLedToPeriodicBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int periods) |
uwp | async Task<int> linkLedToPeriodicBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int periods) |
py | linkLedToPeriodicBlinkSeq( | ledIndex, count, seqIndex, periods) |
php | function linkLedToPeriodicBlinkSeq( | $ledIndex, $count, $seqIndex, $periods) |
ts | async linkLedToPeriodicBlinkSeq( | ledIndex: number, count: number, seqIndex: number, periods: number): Promise<number> |
es | async linkLedToPeriodicBlinkSeq( | ledIndex, count, seqIndex, periods) |
dnp | int linkLedToPeriodicBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int periods) |
cp | int linkLedToPeriodicBlinkSeq( | int ledIndex, |
int count, | ||
int seqIndex, | ||
int periods) |
cmd | YColorLedCluster target linkLedToPeriodicBlinkSeq | ledIndex count seqIndex periods |
Ces LEDs commenceront à exécuter la séquence dès que son exécution sera lancé à l'aide de startBlinkSeq. Cette fonction précalcule un décalage entre les LEDs de sorte à ce que le nombre choisi de périodes de la séquence soit visible sur le groupe de LEDs (effet d'onde).
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
seqIndex | index de la séquence. |
periods | nombre de périodes à répartir entre les LEDs. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Met en cache les valeurs courantes du cluster de LEDs RGB, avec une durée de validité spécifiée.
js | function load( | msValidity) |
cpp | YRETCODE load( | int msValidity) |
m | -(YRETCODE) load | : (u64) msValidity |
pas | YRETCODE load( | msValidity: u64): YRETCODE |
vb | function load( | ByVal msValidity As Long) As YRETCODE |
cs | YRETCODE load( | ulong msValidity) |
java | int load( | long msValidity) |
py | load( | msValidity) |
php | function load( | $msValidity) |
ts | async load( | msValidity: number): Promise<number> |
es | async load( | msValidity) |
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Paramètres :
msValidity | un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Retourne la valeur actuelle d'un attribut spécifique de la fonction, sous forme de texte, le plus rapidement possible mais sans passer par le cache.
js | function loadAttribute( | attrName) |
cpp | string loadAttribute( | string attrName) |
m | -(NSString*) loadAttribute | : (NSString*) attrName |
pas | string loadAttribute( | attrName: string): string |
vb | function loadAttribute( | ByVal attrName As String) As String |
cs | string loadAttribute( | string attrName) |
java | String loadAttribute( | String attrName) |
uwp | async Task<string> loadAttribute( | string attrName) |
py | loadAttribute( | attrName) |
php | function loadAttribute( | $attrName) |
ts | async loadAttribute( | attrName: string): Promise<string> |
es | async loadAttribute( | attrName) |
dnp | string loadAttribute( | string attrName) |
cp | string loadAttribute( | string attrName) |
Paramètres :
attrName | le nom de l'attribut désiré |
Retourne :
une chaîne de caractères représentant la valeur actuelle de l'attribut.
En cas d'erreur, déclenche une exception ou retourne un chaîne vide.
Met en cache les valeurs courantes du cluster de LEDs RGB, avec une durée de validité spécifiée.
js | function load_async( | msValidity, callback, context) |
Par défaut, lorsqu'on accède à un module, tous les attributs des fonctions du module sont automatiquement mises en cache pour la durée standard (5 ms). Cette méthode peut être utilisée pour marquer occasionellement les données cachées comme valides pour une plus longue période, par exemple dans le but de réduire le trafic réseau.
Cette version asynchrone n'existe qu'en Javascript. Elle utilise une fonction de callback plutôt qu'une simple valeur de retour, pour éviter de bloquer la machine virtuelle Javascript avec une attente active.
Paramètres :
msValidity | un entier correspondant à la durée de validité attribuée aux les paramètres chargés, en millisecondes |
callback | fonction de callback qui sera appelée dès que le résultat sera connu. La fonction callback reçoit trois arguments: le contexte fourni par l'appelant, l'objet fonction concerné et le code d'erreur (ou YAPI.SUCCESS) |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout : le résultat sera passé en paramètre à la fonction de callback.
Désactive l'envoi de chaque changement de la valeur publiée au hub parent.
js | function muteValueCallbacks( | ) |
cpp | int muteValueCallbacks( | ) |
m | -(int) muteValueCallbacks |
pas | LongInt muteValueCallbacks( | ): LongInt |
vb | function muteValueCallbacks( | ) As Integer |
cs | int muteValueCallbacks( | ) |
java | int muteValueCallbacks( | ) |
uwp | async Task<int> muteValueCallbacks( | ) |
py | muteValueCallbacks( | ) |
php | function muteValueCallbacks( | ) |
ts | async muteValueCallbacks( | ): Promise<number> |
es | async muteValueCallbacks( | ) |
dnp | int muteValueCallbacks( | ) |
cp | int muteValueCallbacks( | ) |
cmd | YColorLedCluster target muteValueCallbacks |
Vous pouvez utiliser cette fonction pour économiser la bande passante et le CPU sur les machines de faible puissance, ou pour éviter le déclanchement de callbacks HTTP. N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Continue l'énumération des clusters de LEDs RGB commencée à l'aide de yFirstColorLedCluster() Attention, vous ne pouvez faire aucune supposition sur l'ordre dans lequel les clusters de LEDs RGB sont retournés.
js | function nextColorLedCluster( | ) |
cpp | YColorLedCluster * nextColorLedCluster( | ) |
m | -(nullable YColorLedCluster*) nextColorLedCluster |
pas | TYColorLedCluster nextColorLedCluster( | ): TYColorLedCluster |
vb | function nextColorLedCluster( | ) As YColorLedCluster |
cs | YColorLedCluster nextColorLedCluster( | ) |
java | YColorLedCluster nextColorLedCluster( | ) |
uwp | YColorLedCluster nextColorLedCluster( | ) |
py | nextColorLedCluster( | ) |
php | function nextColorLedCluster( | ) |
ts | nextColorLedCluster( | ): YColorLedCluster | null |
es | nextColorLedCluster( | ) |
Si vous souhaitez retrouver un cluster de LEDs RGB spécifique, utilisez ColorLedCluster.findColorLedCluster() avec un hardwareID ou un nom logique.
Retourne :
un pointeur sur un objet YColorLedCluster accessible en ligne, ou null lorsque l'énumération est terminée.
Enregistre la fonction de callback qui est appelée à chaque changement de la valeur publiée.
js | function registerValueCallback( | callback) |
cpp | int registerValueCallback( | YColorLedClusterValueCallback callback) |
m | -(int) registerValueCallback | : (YColorLedClusterValueCallback _Nullable) callback |
pas | LongInt registerValueCallback( | callback: TYColorLedClusterValueCallback): LongInt |
vb | function registerValueCallback( | ByVal callback As YColorLedClusterValueCallback) As Integer |
cs | int registerValueCallback( | ValueCallback callback) |
java | int registerValueCallback( | UpdateCallback callback) |
uwp | async Task<int> registerValueCallback( | ValueCallback callback) |
py | registerValueCallback( | callback) |
php | function registerValueCallback( | $callback) |
ts | async registerValueCallback( | callback: YColorLedClusterValueCallback | null): Promise<number> |
es | async registerValueCallback( | callback) |
Ce callback n'est appelé que durant l'exécution de ySleep ou yHandleEvents. Cela permet à l'appelant de contrôler quand les callback peuvent se produire. Il est important d'appeler l'une de ces deux fonctions périodiquement pour garantir que les callback ne soient pas appelés trop tard. Pour désactiver un callback, il suffit d'appeler cette méthode en lui passant un pointeur nul.
Paramètres :
callback | la fonction de callback à rappeler, ou un pointeur nul. La fonction de callback doit accepter deux arguments: l'object fonction dont la valeur a changé, et la chaîne de caractère décrivant la nouvelle valeur publiée. |
Stoppe l'exécution et efface le contenu d'une séquence.
js | function resetBlinkSeq( | seqIndex) |
cpp | int resetBlinkSeq( | int seqIndex) |
m | -(int) resetBlinkSeq | : (int) seqIndex |
pas | LongInt resetBlinkSeq( | seqIndex: LongInt): LongInt |
vb | function resetBlinkSeq( | ByVal seqIndex As Integer) As Integer |
cs | int resetBlinkSeq( | int seqIndex) |
java | int resetBlinkSeq( | int seqIndex) |
uwp | async Task<int> resetBlinkSeq( | int seqIndex) |
py | resetBlinkSeq( | seqIndex) |
php | function resetBlinkSeq( | $seqIndex) |
ts | async resetBlinkSeq( | seqIndex: number): Promise<number> |
es | async resetBlinkSeq( | seqIndex) |
dnp | int resetBlinkSeq( | int seqIndex) |
cp | int resetBlinkSeq( | int seqIndex) |
cmd | YColorLedCluster target resetBlinkSeq | seqIndex |
Les LEDs liées à cette séquence ne seront plus mises à jour.
Paramètres :
seqIndex | index de la séquence à réinitialiser. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Configure une transition RGB vers une liste de couleurs RGB, pixel par pixel.
js | function rgbArrayOfs_move( | ledIndex, rgbList, delay) |
cpp | int rgbArrayOfs_move( | int ledIndex, vector<int> rgbList, int delay) |
m | -(int) rgbArrayOfs_move | : (int) ledIndex |
: (NSMutableArray*) rgbList | ||
: (int) delay |
pas | LongInt rgbArrayOfs_move( | ledIndex: LongInt, |
rgbList: TLongIntArray, | ||
delay: LongInt): LongInt |
vb | procedure rgbArrayOfs_move( | ByVal ledIndex As Integer, |
ByVal rgbList As List(Of) |
cs | int rgbArrayOfs_move( | int ledIndex, |
List<int> rgbList, | ||
int delay) |
java | int rgbArrayOfs_move( | int ledIndex, |
ArrayList<Integer> rgbList, | ||
int delay) |
uwp | async Task<int> rgbArrayOfs_move( | int ledIndex, |
List<int> rgbList, | ||
int delay) |
py | rgbArrayOfs_move( | ledIndex, rgbList, delay) |
php | function rgbArrayOfs_move( | $ledIndex, $rgbList, $delay) |
ts | async rgbArrayOfs_move( | ledIndex: number, rgbList: number[], delay: number): Promise<number> |
es | async rgbArrayOfs_move( | ledIndex, rgbList, delay) |
dnp | int rgbArrayOfs_move( | int ledIndex, int[] rgbList, int delay) |
cp | int rgbArrayOfs_move( | int ledIndex, |
vector<int> rgbList, | ||
int delay) |
cmd | YColorLedCluster target rgbArrayOfs_move | ledIndex rgbList delay |
Le premier entier correspond à la couleur RGB finale pour la première LED, l'entier suivant à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être modifiée |
rgbList | la liste de valeurs RGB (24 bits) finales désirées, au format 0xRRGGBB |
delay | durée de la transition en ms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Configure une transition RGB vers une liste de couleurs RGB, pixel par pixel.
js | function rgbArray_move( | rgbList, delay) |
cpp | int rgbArray_move( | vector<int> rgbList, int delay) |
m | -(int) rgbArray_move | : (NSMutableArray*) rgbList : (int) delay |
pas | LongInt rgbArray_move( | rgbList: TLongIntArray, delay: LongInt): LongInt |
vb | procedure rgbArray_move( | ByVal rgbList As List(Of) |
cs | int rgbArray_move( | List<int> rgbList, int delay) |
java | int rgbArray_move( | ArrayList<Integer> rgbList, int delay) |
uwp | async Task<int> rgbArray_move( | List<int> rgbList, int delay) |
py | rgbArray_move( | rgbList, delay) |
php | function rgbArray_move( | $rgbList, $delay) |
ts | async rgbArray_move( | rgbList: number[], delay: number): Promise<number> |
es | async rgbArray_move( | rgbList, delay) |
dnp | int rgbArray_move( | int[] rgbList, int delay) |
cp | int rgbArray_move( | vector<int> rgbList, int delay) |
cmd | YColorLedCluster target rgbArray_move | rgbList delay |
Le premier entier correspond à la couleur RGB finale pour la première LED, l'entier suivant à la LED suivante, etc.
Paramètres :
rgbList | la liste de valeurs RGB (24 bits) finales désirées, au format 0xRRGGBB |
delay | durée de la transition en ms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Permet de faire passer un groupe de LED adjacentes de la couleur courante à une autre, de manière continue et indépendante.
js | function rgb_move( | ledIndex, count, rgbValue, delay) |
cpp | int rgb_move( | int ledIndex, int count, int rgbValue, int delay) |
m | -(int) rgb_move | : (int) ledIndex |
: (int) count | ||
: (int) rgbValue | ||
: (int) delay |
pas | LongInt rgb_move( | ledIndex: LongInt, |
count: LongInt, | ||
rgbValue: LongInt, | ||
delay: LongInt): LongInt |
vb | function rgb_move( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal rgbValue As Integer, | ||
ByVal delay As Integer) As Integer |
cs | int rgb_move( | int ledIndex, int count, int rgbValue, int delay) |
java | int rgb_move( | int ledIndex, int count, int rgbValue, int delay) |
uwp | async Task<int> rgb_move( | int ledIndex, |
int count, | ||
int rgbValue, | ||
int delay) |
py | rgb_move( | ledIndex, count, rgbValue, delay) |
php | function rgb_move( | $ledIndex, $count, $rgbValue, $delay) |
ts | async rgb_move( | ledIndex: number, count: number, rgbValue: number, delay: number): Promise<number> |
es | async rgb_move( | ledIndex, count, rgbValue, delay) |
dnp | int rgb_move( | int ledIndex, int count, int rgbValue, int delay) |
cp | int rgb_move( | int ledIndex, int count, int rgbValue, int delay) |
cmd | YColorLedCluster target rgb_move | ledIndex count rgbValue delay |
La transition se fait dans l'espace RGB.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
rgbValue | nouvelle couleur (0xRRGGBB) |
delay | durée de la transition enms. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Sauve la configuration d'une séquence.
js | function saveBlinkSeq( | seqIndex) |
cpp | int saveBlinkSeq( | int seqIndex) |
m | -(int) saveBlinkSeq | : (int) seqIndex |
pas | LongInt saveBlinkSeq( | seqIndex: LongInt): LongInt |
vb | function saveBlinkSeq( | ByVal seqIndex As Integer) As Integer |
cs | int saveBlinkSeq( | int seqIndex) |
java | int saveBlinkSeq( | int seqIndex) |
uwp | async Task<int> saveBlinkSeq( | int seqIndex) |
py | saveBlinkSeq( | seqIndex) |
php | function saveBlinkSeq( | $seqIndex) |
ts | async saveBlinkSeq( | seqIndex: number): Promise<number> |
es | async saveBlinkSeq( | seqIndex) |
dnp | int saveBlinkSeq( | int seqIndex) |
cp | int saveBlinkSeq( | int seqIndex) |
cmd | YColorLedCluster target saveBlinkSeq | seqIndex |
Attention, seul les paramètres de la séquence sont sauvés. Pour sauver le choix de séquence des LEDs il faut appeler la méthode saveLedsConfigAtPowerOn().
Paramètres :
seqIndex | index de la séquence à lancer. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Sauve la configuration de démarrage des LEDs.
js | function saveLedsConfigAtPowerOn( | ) |
cpp | int saveLedsConfigAtPowerOn( | ) |
m | -(int) saveLedsConfigAtPowerOn |
pas | LongInt saveLedsConfigAtPowerOn( | ): LongInt |
vb | function saveLedsConfigAtPowerOn( | ) As Integer |
cs | int saveLedsConfigAtPowerOn( | ) |
java | int saveLedsConfigAtPowerOn( | ) |
uwp | async Task<int> saveLedsConfigAtPowerOn( | ) |
py | saveLedsConfigAtPowerOn( | ) |
php | function saveLedsConfigAtPowerOn( | ) |
ts | async saveLedsConfigAtPowerOn( | ): Promise<number> |
es | async saveLedsConfigAtPowerOn( | ) |
dnp | int saveLedsConfigAtPowerOn( | ) |
cp | int saveLedsConfigAtPowerOn( | ) |
cmd | YColorLedCluster target saveLedsConfigAtPowerOn |
Cela inclut la couleur de démarrage ou le choix de séquence de démarrage pour toutes les LEDs. Attention, si des LEDs sont liées à une séquence il faut appeler la méthode saveBlinkSeq() en plus pour sauver la définition de la séquence.
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie le nombre de LED actuellement gérées par le module.
js | function set_activeLedCount( | newval) |
cpp | int set_activeLedCount( | int newval) |
m | -(int) setActiveLedCount | : (int) newval |
pas | integer set_activeLedCount( | newval: LongInt): integer |
vb | function set_activeLedCount( | ByVal newval As Integer) As Integer |
cs | int set_activeLedCount( | int newval) |
java | int set_activeLedCount( | int newval) |
uwp | async Task<int> set_activeLedCount( | int newval) |
py | set_activeLedCount( | newval) |
php | function set_activeLedCount( | $newval) |
ts | async set_activeLedCount( | newval: number): Promise<number> |
es | async set_activeLedCount( | newval) |
dnp | int set_activeLedCount( | int newval) |
cp | int set_activeLedCount( | int newval) |
cmd | YColorLedCluster target set_activeLedCount | newval |
N'oubliez pas d'appeler la méthode saveToFlash() du module si vous désirez que le réglage soit préservé au prochain redémarrage.
Paramètres :
newval | un entier représentant le nombre de LED actuellement gérées par le module |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Change la vitesse d'exécution d'une séquence, en pour mille.
js | function set_blinkSeqSpeed( | seqIndex, speed) |
cpp | int set_blinkSeqSpeed( | int seqIndex, int speed) |
m | -(int) setBlinkSeqSpeed | : (int) seqIndex |
: (int) speed |
pas | LongInt set_blinkSeqSpeed( | seqIndex: LongInt, speed: LongInt): LongInt |
vb | function set_blinkSeqSpeed( | ByVal seqIndex As Integer, |
ByVal speed As Integer) As Integer |
cs | int set_blinkSeqSpeed( | int seqIndex, int speed) |
java | int set_blinkSeqSpeed( | int seqIndex, int speed) |
uwp | async Task<int> set_blinkSeqSpeed( | int seqIndex, int speed) |
py | set_blinkSeqSpeed( | seqIndex, speed) |
php | function set_blinkSeqSpeed( | $seqIndex, $speed) |
ts | async set_blinkSeqSpeed( | seqIndex: number, speed: number): Promise<number> |
es | async set_blinkSeqSpeed( | seqIndex, speed) |
dnp | int set_blinkSeqSpeed( | int seqIndex, int speed) |
cp | int set_blinkSeqSpeed( | int seqIndex, int speed) |
cmd | YColorLedCluster target set_blinkSeqSpeed | seqIndex speed |
La vitesse d'exécution naturelle est de 1000 pour mille. En configurant une vitesse inférieure, on peut jouer la séquence au ralenti. Une vitesse négative permet même de jouer la séquence à l'envers.
Paramètres :
seqIndex | index de la séquence à lancer. |
speed | vitesse d'exécution de la séquence (-1000...1000). |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Configure une séquence pour qu'elle démarre automatiquement au démarrage du module.
js | function set_blinkSeqStateAtPowerOn( | seqIndex, autostart) |
cpp | int set_blinkSeqStateAtPowerOn( | int seqIndex, int autostart) |
m | -(int) setBlinkSeqStateAtPowerOn | : (int) seqIndex |
: (int) autostart |
pas | LongInt set_blinkSeqStateAtPowerOn( | seqIndex: LongInt, |
autostart: LongInt): LongInt |
vb | function set_blinkSeqStateAtPowerOn( | ByVal seqIndex As Integer, |
ByVal autostart As Integer) As Integer |
cs | int set_blinkSeqStateAtPowerOn( | int seqIndex, int autostart) |
java | int set_blinkSeqStateAtPowerOn( | int seqIndex, int autostart) |
uwp | async Task<int> set_blinkSeqStateAtPowerOn( | int seqIndex, |
int autostart) |
py | set_blinkSeqStateAtPowerOn( | seqIndex, autostart) |
php | function set_blinkSeqStateAtPowerOn( | $seqIndex, $autostart) |
ts | async set_blinkSeqStateAtPowerOn( | seqIndex: number, autostart: number): Promise<number> |
es | async set_blinkSeqStateAtPowerOn( | seqIndex, autostart) |
dnp | int set_blinkSeqStateAtPowerOn( | int seqIndex, int autostart) |
cp | int set_blinkSeqStateAtPowerOn( | int seqIndex, int autostart) |
cmd | YColorLedCluster target set_blinkSeqStateAtPowerOn | seqIndex autostart |
Attention, la durée totale d'une séquence doit être non nulle pour pouvoir être lancée. N'oubliez pas d'appeler saveBlinkSeq() pour sauvegarder la modification dans la mémoire flash du module.
Paramètres :
seqIndex | index de la séquence concernée. |
autostart | 0 pour que la séquence soit arrêtée et 1 pour qu'elle démarre. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie la couleur courante d'un groupe de LED consécutives en utilisant une couleur HSL .
js | function set_hslColor( | ledIndex, count, hslValue) |
cpp | int set_hslColor( | int ledIndex, int count, int hslValue) |
m | -(int) setHslColor | : (int) ledIndex |
: (int) count | ||
: (int) hslValue |
pas | LongInt set_hslColor( | ledIndex: LongInt, |
count: LongInt, | ||
hslValue: LongInt): LongInt |
vb | function set_hslColor( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal hslValue As Integer) As Integer |
cs | int set_hslColor( | int ledIndex, int count, int hslValue) |
java | int set_hslColor( | int ledIndex, int count, int hslValue) |
uwp | async Task<int> set_hslColor( | int ledIndex, int count, int hslValue) |
py | set_hslColor( | ledIndex, count, hslValue) |
php | function set_hslColor( | $ledIndex, $count, $hslValue) |
ts | async set_hslColor( | ledIndex: number, count: number, hslValue: number): Promise<number> |
es | async set_hslColor( | ledIndex, count, hslValue) |
dnp | int set_hslColor( | int ledIndex, int count, int hslValue) |
cp | int set_hslColor( | int ledIndex, int count, int hslValue) |
cmd | YColorLedCluster target set_hslColor | ledIndex count hslValue |
L'encodage est réalisé de la manière suivante: 0xHHSSLL.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
hslValue | nouvelle couleur. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Envoie des couleurs HSL 24 bits (fournie sous forme d'une liste d'entiers) sur l'affichage LED HSL.
js | function set_hslColorArray( | ledIndex, hslList) |
cpp | int set_hslColorArray( | int ledIndex, vector<int> hslList) |
m | -(int) setHslColorArray | : (int) ledIndex |
: (NSMutableArray*) hslList |
pas | LongInt set_hslColorArray( | ledIndex: LongInt, |
hslList: TLongIntArray): LongInt |
vb | procedure set_hslColorArray( | ByVal ledIndex As Integer, |
ByVal hslList As List(Of) |
cs | int set_hslColorArray( | int ledIndex, List<int> hslList) |
java | int set_hslColorArray( | int ledIndex, ArrayList<Integer> hslList) |
uwp | async Task<int> set_hslColorArray( | int ledIndex, List<int> hslList) |
py | set_hslColorArray( | ledIndex, hslList) |
php | function set_hslColorArray( | $ledIndex, $hslList) |
ts | async set_hslColorArray( | ledIndex: number, hslList: number[]): Promise<number> |
es | async set_hslColorArray( | ledIndex, hslList) |
dnp | int set_hslColorArray( | int ledIndex, int[] hslList) |
cp | int set_hslColorArray( | int ledIndex, vector<int> hslList) |
cmd | YColorLedCluster target set_hslColorArray | ledIndex hslList |
Le premier entier correspond à la couleur HSL de la LED indiquée en argument, l'entier suivant à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être modifiée |
hslList | la liste de valeurs HSL (24 bits) à envoyer, au format 0xHHSSLL |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie la couleur au démarrage d'un groupe de LED consécutives en utilisant une couleur HSL.
js | function set_hslColorAtPowerOn( | ledIndex, count, hslValue) |
cpp | int set_hslColorAtPowerOn( | int ledIndex, int count, int hslValue) |
m | -(int) setHslColorAtPowerOn | : (int) ledIndex |
: (int) count | ||
: (int) hslValue |
pas | LongInt set_hslColorAtPowerOn( | ledIndex: LongInt, |
count: LongInt, | ||
hslValue: LongInt): LongInt |
vb | function set_hslColorAtPowerOn( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal hslValue As Integer) As Integer |
cs | int set_hslColorAtPowerOn( | int ledIndex, |
int count, | ||
int hslValue) |
java | int set_hslColorAtPowerOn( | int ledIndex, int count, int hslValue) |
uwp | async Task<int> set_hslColorAtPowerOn( | int ledIndex, |
int count, | ||
int hslValue) |
py | set_hslColorAtPowerOn( | ledIndex, count, hslValue) |
php | function set_hslColorAtPowerOn( | $ledIndex, $count, $hslValue) |
ts | async set_hslColorAtPowerOn( | ledIndex: number, count: number, hslValue: number): Promise<number> |
es | async set_hslColorAtPowerOn( | ledIndex, count, hslValue) |
dnp | int set_hslColorAtPowerOn( | int ledIndex, |
int count, | ||
int hslValue) |
cp | int set_hslColorAtPowerOn( | int ledIndex, |
int count, | ||
int hslValue) |
cmd | YColorLedCluster target set_hslColorAtPowerOn | ledIndex count hslValue |
L'encodage est réalisé de la manière suivante: 0xHHSSLL. N'oubliez pas d'appeler saveLedsConfigAtPowerOn() pour sauvegarder la modification dans la mémoire flash du module.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
hslValue | nouvelle couleur. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Envoie un objet binaire tel quel sur l'affichage LED HSL.
js | function set_hslColorBuffer( | ledIndex, buff) |
cpp | int set_hslColorBuffer( | int ledIndex, string buff) |
m | -(int) setHslColorBuffer | : (int) ledIndex |
: (NSData*) buff |
pas | LongInt set_hslColorBuffer( | ledIndex: LongInt, buff: TByteArray): LongInt |
vb | procedure set_hslColorBuffer( | ByVal ledIndex As Integer, ByVal buff As Byte() |
cs | int set_hslColorBuffer( | int ledIndex, byte[] buff) |
java | int set_hslColorBuffer( | int ledIndex, byte[] buff) |
uwp | async Task<int> set_hslColorBuffer( | int ledIndex, byte[] buff) |
py | set_hslColorBuffer( | ledIndex, buff) |
php | function set_hslColorBuffer( | $ledIndex, $buff) |
ts | async set_hslColorBuffer( | ledIndex: number, buff: Uint8Array): Promise<number> |
es | async set_hslColorBuffer( | ledIndex, buff) |
dnp | int set_hslColorBuffer( | int ledIndex, byte[] buff) |
cp | int set_hslColorBuffer( | int ledIndex, string buff) |
cmd | YColorLedCluster target set_hslColorBuffer | ledIndex buff |
Les trois premiers octets correspondent aux composantes HSL de la LED indiquée en argument, les trois octets suivants à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être modifiée |
buff | l'objet binaire à envoyer |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie le type de LEDs RGB actuellement gérées par le module.
js | function set_ledType( | newval) |
cpp | int set_ledType( | Y_LEDTYPE_enum newval) |
m | -(int) setLedType | : (Y_LEDTYPE_enum) newval |
pas | integer set_ledType( | newval: Integer): integer |
vb | function set_ledType( | ByVal newval As Integer) As Integer |
cs | int set_ledType( | int newval) |
java | int set_ledType( | int newval) |
uwp | async Task<int> set_ledType( | int newval) |
py | set_ledType( | newval) |
php | function set_ledType( | $newval) |
ts | async set_ledType( | newval: YColorLedCluster_LedType): Promise<number> |
es | async set_ledType( | newval) |
dnp | int set_ledType( | int newval) |
cp | int set_ledType( | int newval) |
cmd | YColorLedCluster target set_ledType | newval |
N'oubliez pas d'appeler la méthode saveToFlash() du module si vous désirez que le réglage soit préservé au prochain redémarrage.
Paramètres :
newval | soit YColorLedCluster.LEDTYPE_RGB, soit YColorLedCluster.LEDTYPE_RGBW, selon le type de LEDs RGB actuellement gérées par le module |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie le nom logique du cluster de LEDs RGB.
js | function set_logicalName( | newval) |
cpp | int set_logicalName( | string newval) |
m | -(int) setLogicalName | : (NSString*) newval |
pas | integer set_logicalName( | newval: string): integer |
vb | function set_logicalName( | ByVal newval As String) As Integer |
cs | int set_logicalName( | string newval) |
java | int set_logicalName( | String newval) |
uwp | async Task<int> set_logicalName( | string newval) |
py | set_logicalName( | newval) |
php | function set_logicalName( | $newval) |
ts | async set_logicalName( | newval: string): Promise<number> |
es | async set_logicalName( | newval) |
dnp | int set_logicalName( | string newval) |
cp | int set_logicalName( | string newval) |
cmd | YColorLedCluster target set_logicalName | newval |
Vous pouvez utiliser yCheckLogicalName() pour vérifier si votre paramètre est valide. N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Paramètres :
newval | une chaîne de caractères représentant le nom logique du cluster de LEDs RGB. |
Retourne :
YAPI.SUCCESS si l'appel se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie la couleur courante d'un groupe de LED consécutives en utilisant une couleur RGB (Rouge Vert Bleu).
js | function set_rgbColor( | ledIndex, count, rgbValue) |
cpp | int set_rgbColor( | int ledIndex, int count, int rgbValue) |
m | -(int) setRgbColor | : (int) ledIndex |
: (int) count | ||
: (int) rgbValue |
pas | LongInt set_rgbColor( | ledIndex: LongInt, |
count: LongInt, | ||
rgbValue: LongInt): LongInt |
vb | function set_rgbColor( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal rgbValue As Integer) As Integer |
cs | int set_rgbColor( | int ledIndex, int count, int rgbValue) |
java | int set_rgbColor( | int ledIndex, int count, int rgbValue) |
uwp | async Task<int> set_rgbColor( | int ledIndex, int count, int rgbValue) |
py | set_rgbColor( | ledIndex, count, rgbValue) |
php | function set_rgbColor( | $ledIndex, $count, $rgbValue) |
ts | async set_rgbColor( | ledIndex: number, count: number, rgbValue: number): Promise<number> |
es | async set_rgbColor( | ledIndex, count, rgbValue) |
dnp | int set_rgbColor( | int ledIndex, int count, int rgbValue) |
cp | int set_rgbColor( | int ledIndex, int count, int rgbValue) |
cmd | YColorLedCluster target set_rgbColor | ledIndex count rgbValue |
L'encodage est réalisé de la manière suivante: 0xRRGGBB.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
rgbValue | nouvelle couleur. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Envoie des couleurs RGB 24 bits (fournie sous forme d'une liste d'entiers) sur l'affichage LED RGB.
js | function set_rgbColorArray( | ledIndex, rgbList) |
cpp | int set_rgbColorArray( | int ledIndex, vector<int> rgbList) |
m | -(int) setRgbColorArray | : (int) ledIndex |
: (NSMutableArray*) rgbList |
pas | LongInt set_rgbColorArray( | ledIndex: LongInt, |
rgbList: TLongIntArray): LongInt |
vb | procedure set_rgbColorArray( | ByVal ledIndex As Integer, |
ByVal rgbList As List(Of) |
cs | int set_rgbColorArray( | int ledIndex, List<int> rgbList) |
java | int set_rgbColorArray( | int ledIndex, ArrayList<Integer> rgbList) |
uwp | async Task<int> set_rgbColorArray( | int ledIndex, List<int> rgbList) |
py | set_rgbColorArray( | ledIndex, rgbList) |
php | function set_rgbColorArray( | $ledIndex, $rgbList) |
ts | async set_rgbColorArray( | ledIndex: number, rgbList: number[]): Promise<number> |
es | async set_rgbColorArray( | ledIndex, rgbList) |
dnp | int set_rgbColorArray( | int ledIndex, int[] rgbList) |
cp | int set_rgbColorArray( | int ledIndex, vector<int> rgbList) |
cmd | YColorLedCluster target set_rgbColorArray | ledIndex rgbList |
Le premier entier correspond à la couleur RGB de la LED indiquée en argument, l'entier suivant à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être modifiée |
rgbList | la liste de valeurs RGB (24 bits) à envoyer, au format 0xRRGGBB |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Modifie la couleur au démarrage d'un groupe de LED consécutives en utilisant une couleur RGB (Rouge Vert Bleu).
js | function set_rgbColorAtPowerOn( | ledIndex, count, rgbValue) |
cpp | int set_rgbColorAtPowerOn( | int ledIndex, int count, int rgbValue) |
m | -(int) setRgbColorAtPowerOn | : (int) ledIndex |
: (int) count | ||
: (int) rgbValue |
pas | LongInt set_rgbColorAtPowerOn( | ledIndex: LongInt, |
count: LongInt, | ||
rgbValue: LongInt): LongInt |
vb | function set_rgbColorAtPowerOn( | ByVal ledIndex As Integer, |
ByVal count As Integer, | ||
ByVal rgbValue As Integer) As Integer |
cs | int set_rgbColorAtPowerOn( | int ledIndex, |
int count, | ||
int rgbValue) |
java | int set_rgbColorAtPowerOn( | int ledIndex, int count, int rgbValue) |
uwp | async Task<int> set_rgbColorAtPowerOn( | int ledIndex, |
int count, | ||
int rgbValue) |
py | set_rgbColorAtPowerOn( | ledIndex, count, rgbValue) |
php | function set_rgbColorAtPowerOn( | $ledIndex, $count, $rgbValue) |
ts | async set_rgbColorAtPowerOn( | ledIndex: number, count: number, rgbValue: number): Promise<number> |
es | async set_rgbColorAtPowerOn( | ledIndex, count, rgbValue) |
dnp | int set_rgbColorAtPowerOn( | int ledIndex, |
int count, | ||
int rgbValue) |
cp | int set_rgbColorAtPowerOn( | int ledIndex, |
int count, | ||
int rgbValue) |
cmd | YColorLedCluster target set_rgbColorAtPowerOn | ledIndex count rgbValue |
L'encodage est réalisé de la manière suivante: 0xRRGGBB. N'oubliez pas d'appeler saveLedsConfigAtPowerOn() pour sauvegarder la modification dans la mémoire flash du module.
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LED consécutives affectés. |
rgbValue | nouvelle couleur. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Envoie un objet binaire tel quel sur l'affichage LED RGB.
js | function set_rgbColorBuffer( | ledIndex, buff) |
cpp | int set_rgbColorBuffer( | int ledIndex, string buff) |
m | -(int) setRgbColorBuffer | : (int) ledIndex |
: (NSData*) buff |
pas | LongInt set_rgbColorBuffer( | ledIndex: LongInt, buff: TByteArray): LongInt |
vb | procedure set_rgbColorBuffer( | ByVal ledIndex As Integer, ByVal buff As Byte() |
cs | int set_rgbColorBuffer( | int ledIndex, byte[] buff) |
java | int set_rgbColorBuffer( | int ledIndex, byte[] buff) |
uwp | async Task<int> set_rgbColorBuffer( | int ledIndex, byte[] buff) |
py | set_rgbColorBuffer( | ledIndex, buff) |
php | function set_rgbColorBuffer( | $ledIndex, $buff) |
ts | async set_rgbColorBuffer( | ledIndex: number, buff: Uint8Array): Promise<number> |
es | async set_rgbColorBuffer( | ledIndex, buff) |
dnp | int set_rgbColorBuffer( | int ledIndex, byte[] buff) |
cp | int set_rgbColorBuffer( | int ledIndex, string buff) |
cmd | YColorLedCluster target set_rgbColorBuffer | ledIndex buff |
Les trois premiers octets correspondent aux composantes RGB de la LED indiquée en argument, les trois octets suivants à la LED suivante, etc.
Paramètres :
ledIndex | index de la première LED qui doit être modifiée |
buff | l'objet binaire à envoyer |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Enregistre un contexte libre dans l'attribut userData de la fonction, afin de le retrouver plus tard à l'aide de la méthode get_userData.
js | function set_userData( | data) |
cpp | void set_userData( | void * data) |
m | -(void) setUserData | : (id) data |
pas | set_userData( | data: Tobject) |
vb | procedure set_userData( | ByVal data As Object) |
cs | void set_userData( | object data) |
java | void set_userData( | Object data) |
py | set_userData( | data) |
php | function set_userData( | $data) |
ts | async set_userData( | data: object|null): Promise<void> |
es | async set_userData( | data) |
Cet attribut n'es pas utilisé directement par l'API. Il est à la disposition de l'appelant pour stocker un contexte.
Paramètres :
data | objet quelconque à mémoriser |
Démarre l'exécution d'une séquence : toutes les LED liées à cette séquence vont commencer à l'exécuter en boucle.
js | function startBlinkSeq( | seqIndex) |
cpp | int startBlinkSeq( | int seqIndex) |
m | -(int) startBlinkSeq | : (int) seqIndex |
pas | LongInt startBlinkSeq( | seqIndex: LongInt): LongInt |
vb | function startBlinkSeq( | ByVal seqIndex As Integer) As Integer |
cs | int startBlinkSeq( | int seqIndex) |
java | int startBlinkSeq( | int seqIndex) |
uwp | async Task<int> startBlinkSeq( | int seqIndex) |
py | startBlinkSeq( | seqIndex) |
php | function startBlinkSeq( | $seqIndex) |
ts | async startBlinkSeq( | seqIndex: number): Promise<number> |
es | async startBlinkSeq( | seqIndex) |
dnp | int startBlinkSeq( | int seqIndex) |
cp | int startBlinkSeq( | int seqIndex) |
cmd | YColorLedCluster target startBlinkSeq | seqIndex |
Attention, la durée totale d'une séquence doit être non nulle pour pouvoir être lancée.
Paramètres :
seqIndex | index de la séquence à lancer. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Stoppe l'exécution d'une séquence.
js | function stopBlinkSeq( | seqIndex) |
cpp | int stopBlinkSeq( | int seqIndex) |
m | -(int) stopBlinkSeq | : (int) seqIndex |
pas | LongInt stopBlinkSeq( | seqIndex: LongInt): LongInt |
vb | function stopBlinkSeq( | ByVal seqIndex As Integer) As Integer |
cs | int stopBlinkSeq( | int seqIndex) |
java | int stopBlinkSeq( | int seqIndex) |
uwp | async Task<int> stopBlinkSeq( | int seqIndex) |
py | stopBlinkSeq( | seqIndex) |
php | function stopBlinkSeq( | $seqIndex) |
ts | async stopBlinkSeq( | seqIndex: number): Promise<number> |
es | async stopBlinkSeq( | seqIndex) |
dnp | int stopBlinkSeq( | int seqIndex) |
cp | int stopBlinkSeq( | int seqIndex) |
cmd | YColorLedCluster target stopBlinkSeq | seqIndex |
Si la séquence est redémarrée l'exécution repartira du début.
Paramètres :
seqIndex | index de la séquence à stopper. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Délie un groupe de LEDs adjacentes d'une séquence.
js | function unlinkLedFromBlinkSeq( | ledIndex, count) |
cpp | int unlinkLedFromBlinkSeq( | int ledIndex, int count) |
m | -(int) unlinkLedFromBlinkSeq | : (int) ledIndex |
: (int) count |
pas | LongInt unlinkLedFromBlinkSeq( | ledIndex: LongInt, |
count: LongInt): LongInt |
vb | function unlinkLedFromBlinkSeq( | ByVal ledIndex As Integer, |
ByVal count As Integer) As Integer |
cs | int unlinkLedFromBlinkSeq( | int ledIndex, int count) |
java | int unlinkLedFromBlinkSeq( | int ledIndex, int count) |
uwp | async Task<int> unlinkLedFromBlinkSeq( | int ledIndex, int count) |
py | unlinkLedFromBlinkSeq( | ledIndex, count) |
php | function unlinkLedFromBlinkSeq( | $ledIndex, $count) |
ts | async unlinkLedFromBlinkSeq( | ledIndex: number, count: number): Promise<number> |
es | async unlinkLedFromBlinkSeq( | ledIndex, count) |
dnp | int unlinkLedFromBlinkSeq( | int ledIndex, int count) |
cp | int unlinkLedFromBlinkSeq( | int ledIndex, int count) |
cmd | YColorLedCluster target unlinkLedFromBlinkSeq | ledIndex count |
Paramètres :
ledIndex | index de la première LED affectée. |
count | nombre de LEDs consécutives affectées. |
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Réactive l'envoi de chaque changement de la valeur publiée au hub parent.
js | function unmuteValueCallbacks( | ) |
cpp | int unmuteValueCallbacks( | ) |
m | -(int) unmuteValueCallbacks |
pas | LongInt unmuteValueCallbacks( | ): LongInt |
vb | function unmuteValueCallbacks( | ) As Integer |
cs | int unmuteValueCallbacks( | ) |
java | int unmuteValueCallbacks( | ) |
uwp | async Task<int> unmuteValueCallbacks( | ) |
py | unmuteValueCallbacks( | ) |
php | function unmuteValueCallbacks( | ) |
ts | async unmuteValueCallbacks( | ): Promise<number> |
es | async unmuteValueCallbacks( | ) |
dnp | int unmuteValueCallbacks( | ) |
cp | int unmuteValueCallbacks( | ) |
cmd | YColorLedCluster target unmuteValueCallbacks |
Cette fonction annule un précédent appel à muteValueCallbacks(). N'oubliez pas d'appeler la méthode saveToFlash() du module si le réglage doit être préservé.
Retourne :
YAPI.SUCCESS si l'opération se déroule sans erreur.
En cas d'erreur, déclenche une exception ou retourne un code d'erreur négatif.
Attend que toutes les commandes asynchrones en cours d'exécution sur le module soient terminées, et appelle le callback passé en paramètre.
js | function wait_async( | callback, context) |
ts | wait_async( | callback: Function, context: object) |
es | wait_async( | callback, context) |
La fonction callback peut donc librement utiliser des fonctions synchrones ou asynchrones, sans risquer de bloquer la machine virtuelle Javascript.
Paramètres :
callback | fonction de callback qui sera appelée dès que toutes les commandes en cours d'exécution sur le module seront terminées La fonction callback reçoit deux arguments: le contexte fourni par l'appelant et l'objet fonction concerné. |
context | contexte fourni par l'appelant, et qui sera passé tel-quel à la fonction de callback |
Retourne :
rien du tout.
If it is the first time that you use a Yoctopuce module and you do not really know where to start, have a look at the Yoctopuce blog. There is a section dedicated to beginners 64.
Most of Yoctopuce API programming examples are command line programs and require some parameters to work properly. You have to start them from your operating system command prompt, or configure your IDE to run them with the proper parameters. 65.
To work correctly under Linux, the the library needs to have write access to all the Yoctopuce USB peripherals. However, by default under Linux, USB privileges of the non-root users are limited to read access. To avoid having to run the VirtualHub as root, you need to create a new udev rule to authorize one or several users to have write access to the Yoctopuce peripherals.
To add a new udev rule to your installation, you must add a file with a name following the "##-arbitraryName.rules" format, in the "/etc/udev/rules.d" directory. When the system is starting, udev reads all the files with a ".rules" extension in this directory, respecting the alphabetical order (for example, the "51-custom.rules" file is interpreted AFTER the "50-udev-default.rules" file).
The "50-udev-default" file contains the system default udev rules. To modify the default behavior, you therefore need to create a file with a name that starts with a number larger than 50, that will override the system default rules. Note that to add a rule, you need a root access on the system.
In the udev_conf directory of the VirtualHub for Linux66 archive, there are two rule examples which you can use as a basis.
This rule provides all the users with read and write access to the Yoctopuce USB peripherals. Access rights for all other peripherals are not modified. If this scenario suits you, you only need to copy the "51-yoctopuce_all.rules" file into the "/etc/udev/rules.d" directory and to restart your system.
# udev rules to allow write access to all users # for Yoctopuce USB devices SUBSYSTEM=="usb", ATTR{idVendor}=="24e0", MODE="0666"
This rule authorizes the "yoctogroup" group to have read and write access to Yoctopuce USB peripherals. Access rights for all other peripherals are not modified. If this scenario suits you, you only need to copy the "51-yoctopuce_group.rules" file into the "/etc/udev/rules.d" directory and restart your system.
# udev rules to allow write access to all users of "yoctogroup" # for Yoctopuce USB devices SUBSYSTEM=="usb", ATTR{idVendor}=="24e0", MODE="0664", GROUP="yoctogroup"
There are two main flavors of executable on ARM: HF (Hard Float) binaries, and EL (EABI Little Endian) binaries. These two families are not compatible at all. The compatibility of a given ARM platform with of one of these two families depends on the hardware and on the OS build. ArmHL and ArmEL compatibility problems are quite difficult to detect. Most of the time, the OS itself is unable to make a difference between an HF and an EL executable and will return meaningless messages when you try to use the wrong type of binary.
All pre-compiled Yoctopuce binaries are provided in both formats, as two separate ArmHF et ArmEL executables. If you do not know what family your ARM platform belongs to, just try one executable from each family.
If your Yocto-MaxiBuzzer is connected by USB, if its blue led is on, but if the operating system cannot see the module, check that you are using a true USB cable with data wires, and not a charging cable. Charging cables have only power wires.
If when initializing the Yoctopuce API, you obtain the "Another process named xxx is already using yAPI" error message, it means that another application is already using Yoctopuce USB modules. On a single machine only one process can access Yoctopuce modules by USB at a time. You can easily work around this limitation by using a VirtualHub and the network mode 67.
If you Yocto-MaxiBuzzer behaves erratically and/or disconnects itself from the USB bus without apparent reason, check that it is correctly powered. Avoid cables with a length above 2 meters. If needed, insert a powered USB hub 68 69.
If, when performing a call to RegisterHub() with an VirtualHub address, an other previously registered VirtualHub disconnects, make sure the machine running theses VirtualHubs don't have the same Hostname. Same Hostname can happen very easily when the operating system is installed from a monolithic image, Raspberry-PI are the best example. The Yoctopuce API uses serial numbers to communicate with devices and VirtualHub serial number are created on the fly based the hostname of the machine running the VirtualHub.
If, after sending a bunch of commands to a Yoctopuce device, you are under the impression that the last ones have been ignored, typical example is a quick and dirty program meant to configure a device, make sure you used a YAPI.FreeAPI() at the end of the program. Commands are sent to Yoctopuce modules asynchronously thanks to a background thread. When the main program terminates, that thread is killed no matter if some command are left to be sent. However API.FreeAPI() will wait until there is no more commands to send before freeing the API resources and returning.
Yoctopuce strives to reduce the production of electronic waste. If you believe that your Yocto-MaxiBuzzer is not working anymore, start by contacting Yoctopuce support by e-mail to diagnose the failure. Even if you know that the device was damaged by mistake, Yoctopuce engineers might be able to repair it, and thus avoid creating electronic waste.
Waste Electrical and Electronic Equipment (WEEE) If you really want to get rid of your Yocto-MaxiBuzzer, do not throw it away in a trash bin but bring it to your local WEEE recycling point. In this way, it will be disposed properly by a specialized WEEE recycling center.
You can find below a summary of the main technical characteristics of your Yocto-MaxiBuzzer module.
Product ID | YMAXBUZ1 |
Hardware release† | |
USB connector | micro-B |
Width | 58 mm |
Length | 57 mm |
Weight | 24.2 g |
Supported RGB LEDs | WS2812B, WS2812C, SK6812 |
Supported RGBW LEDs | SK6812RGBW |
Max number of LEDs | 150 |
Sound Pressure Level @50cm | 100 dB(A) |
Protection class, according to IEC 61140 | class III |
Normal operating temperature | 5...40 °C |
Extended operating temperature‡ | -25...80 °C |
RoHS compliance | RoHS III (2011/65/UE+2015/863) |
USB Vendor ID | 0x24E0 |
USB Device ID | 0x0098 |
Suggested enclosure | YoctoBox-MaxiBuz |
Harmonized tariff code | 9032.9000 |
Made in | Switzerland |
† These specifications are for the current hardware revision. Specifications for earlier revisions may differ.
‡ The extended temperature range is defined based on components specifications and has been tested during a limited duration (1h). When using the device in harsh environments for a long period of time, we strongly advise to run extensive tests before going to production.