Home

User manual

1. www yoctopuce com 223 21 High level API Reference voltage load_async YVoltage Preloads the voltage sensor cache with a specified validity duration asynchronous version function load_async msValidity callback context 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 trafic 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 YAPT_SUCCESS context caller specific object that is passed as is to the callback function Returns nothing the result is provided to the callback 224 www yoctopuce com 21 High level API Reference voltage nextVoltage YVoltage Continues the enumeration of voltage sensors started using yFirstVoltage function nextVoltage function nextVoltage function nextVoltage YVoltage next
2. 1 8 8 The most common USB 2 connectors A B Mini B Micro A Micro B 3 To connect your Yocto Volt module to a computer you need a USB cable of type A micro B The price of this cable may vary a lot depending on the source look for it under the name USB A to micro B Data cable Make sure not to buy a simple USB charging cable without data connectivity The correct type of cable is available on the Yoctopuce shop 2 The HID driver is the one that takes care of the mouse the keyboard etc 3 Although they existed for some time Mini A connectors are not available anymore http www usb org developers Deprecation_Announcement_052507 pdf 2 www yoctopuce com 1 Introduction If you insert a USB hub between the computer and the Yocto Volt 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 1 2 Optional accessories The accessories below are not necessary to use the Yocto Volt module but might be useful depending on your project These are mostly common products that you can buy from your favourite hacking store To save you the tedious job of looking for them most of them are also available on the Yoctopuce shop Screws and spacers In order to mount the Yocto Volt module you can put small screws in the 2 5mm assembly holes with
3. 20 15 50 Dm nee Jo OU NO ten 7 i Ba 250 a m MAX4 5 All dimensions are in mm Toutes les dimensions sont en mm Yocto Volt ae Scale Echelle Index A Access 95 Accessories 3 Activating 96 Advanced 107 Alternating 9 Android 95 96 Assembly 15 Basic 63 Blueprint 295 C C 69 C 49 54 calibrateFromPoints YVoltage 197 Calibration 112 Callback 44 Characteristics 293 CheckLogicalName YAPI 125 Command 27 117 Compatibility 95 Components 7 Concepts 17 Configuration 12 Connections 15 Current 9 D Dangerous 7 Data 110 271 DataLogger 21 236 Delphi 77 describe YDataLogger 239 describe YModule 152 describe YVoltage 198 Description 27 Direct 9 DisableExceptions YAPI 126 Distribution 16 download YModule 153 Dynamic 83 119 E Electrocution 7 Elements 5 6 EnableExceptions YAPI 127 EnableUSBHost YAPI 128 Error 36 47 54 61 68 74 81 87 93 105 Event 107 F Files 83 Filters 44 FindDataLogger YDataLogger 237 FindModule YModule 150 FindVoltage YVoltage 195 FirstDataLogger YDataLogger 238 FirstModule YModule 151 FirstVoltage YVoltage 196 Fixing 15 forgetAllDataStreams YDataLogger 240 FreeAPI YAPI 129 functionCount YModule 154 functionld YModule 155 functionName YModule 156 Functions 124 functionValue YModule 157 G General 17 27 124 get_advertisedValue YDataLogger 241 get_advertisedValue
4. 325v Alternating voltage for example the voltage of the mains in Europe it varies periodically Note that an alternating voltage is not necessarily symmetrical One can then describe it as the sum of a direct voltage and of an alternating symmetrical voltage 1 The exact term is RMS value www yoctopuce com 9 4 Direct current vs alternating current Asymmetrical alternating voltage It is the sum of a direct voltage and of an alternating voltage For this reason the Yocto Volt provides measures in the shape of a measure of the direct voltage DC coupled with a measure of the alternating voltage AC When you measure a voltage with a Yocto Volt several distinct cases can occur Anon null DC value and a null AC value you are measuring a direct voltage e A non null AC value and an almost null DC value your are measuring a symmetrical alternating voltage Anon null AC value and a non null DC value you are measuring an alternating voltage which is not symmetrical Anon null stable DC value and a completely random AC value you are measuring a voltage which is not stabilized typically a somewhat too cheap AC adapter The Yocto Volt has a 0 01V 0 5 v accuracy for direct voltage The accuracy is especially good under 50V DC However its accuracy for alternating voltage is less good take into account an error of more or less 0 1V 3 at 50 60hz Below 30Hz the lower the frequency is the less sta
5. Gets the YModule object for the device on which the function is located asynchronous version datalogger get_recording Returns the current activation state of the data logger datalogger get_timeUTC Returns the Unix timestamp for current UTC time if known datalogger get_userData Returns the value of the userData attribute as previously stored using method set_userData datalogger isOnline Checks if the data logger is currently reachable without raising any error datalogger isOnline_async callback context Checks if the data logger is currently reachable without raising any error asynchronous version datalogger load msValidity Preloads the data logger cache with a specified validity duration datalogger load_async msValidity callback context Preloads the data logger cache with a specified validity duration asynchronous version datalogger nextDataLogger Continues the enumeration of data loggers started using yFirstDataLogger datalogger registerValueCallback callback Registers the callback function that is invoked on every change of advertised value datalogger set_autoStart newval Changes the default activation state of the data logger on power up datalogger set_logicalName newval Changes the logical name of the data logger datalogger set_recording newval Changes the activation state of the data logger to start stop recording data datalogger set_timeUTC newval
6. Console WriteLine execname lt serial_ number gt Console WriteLine execnamet lt logical name gt Console WriteLine execnamet any g System Threading Thread Sleep 2500 End End Sub Sub Die ByVal msg As String Console WriteLine msg check USB cable End End Sub Sub Main Dim argv As String System Environment GetCommandLineArgs Dim errmsg As String Dim tanger As String Dim sensor As YVoltage Dim sensorDC As YVoltage Nothing Dim sensorAC As YVoltage Nothing Dim m As YModule Nothing If argv Length lt 2 Then Usage target argv 1 REM Setup the APE to use local USB devices Ee yReGuls kerhubi Usbi errmsg lt gt VAPI SUCCESS shen Console WriteLine RegisterHub error errmsg End End If Rianne Many een REM retreive any voltage sensor can be AC or DC sensor yFirstVoltage If sensor Is Nothing Then Die No module connected Else sensor yFindVoltage target voltagel End If REM we need to retreive both DC and AC voltage from the device If sensor isOnline Then m sensor get module sensorDC yFindVoltage m get_serialNumber voltagel sensorAC yFindVoltage m get_serialNumber voltage2 Else Die Module not connected End If While True If Not m isOnline Then Die Module not connected Consoler Write VDE sensorDe ger currenuvalue losiemang ConsolerWrite VAC isensorAG igermcurrenevaluel losers nogi
7. String get_errorMessage def 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 voltage sensor object www yoctopuce com 203 21 High level API Reference voltage get_errorType YVoltage voltage errorType Returns the numerical error code of the latest error with the voltage sensor function get_errorType function get_errorType function get_errorType YRETCODE get_errorType function get_errorType YRETCODE function get_errorType As YRETCODE YRETCODE get_errorType int get_errorType def 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 occured while using the voltage sensor object 204 www yoctopuce com 21 High level API Reference voltage get_friendlyName YVoltage voltage friendlyName Returns a global identifier of the voltage sensor in the format MODULE_NAME FUNCTION_NAME function get_friendlyName function get_friendlyName function get_friendlyName string get_friendlyName NSString friendlyName string get_friendlyName String get_friendlyName def get_friendlyName The returned string uses the logical names of the module and of the voltage sensor if th
8. string function get_hardwareld As String string get_hardwareld String get_hardwareld def get_hardwareld The unique hardware identifier is composed of the device serial number and of the hardware identifier of the function for example THRMCPL1 123456 temperaturel1 Returns a string that uniquely identifies the function ex THRMCPL1 123456 temperaturel On failure throws an exception or returns Y_HARDWAREID_INVALID www yoctopuce com 275 21 High level API Reference dataset get_measures YDataSet dataset measures Returns all measured values currently available for this DataSet as a list of YMeasure objects function get_measures function get_measures function get_measures vector lt YMeasure gt get_measures NSMutableArray measures function get_measures TYMeasureArray function get_measures As List List lt YMeasure gt get_measures ArrayList lt YMeasure gt get_measures def get_measures Each item includes the start of the measure time interval the end of the measure time interval the minimal value observed during the time interval the average value observed during the time interval the maximal value observed during the time interval Before calling this method you should call loadMore to load data from the device You may have to call loadMore several time until all rows are loaded but you can start looking at available data ro
9. 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_hardwareld Returns the unique hardware identifier of the module module get_icon2d 148 www yoctopuce com 21 High level API Reference 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_persistentSettings Returns the current state of persistent module settings module get_productld 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 hardware release version of the module module get_rebootCountdown Returns the remaining number of seconds before the module restarts or zero when no reboot has been scheduled module gt get_serialNumber Returns the serial number of the module as set by the factory module get_upTime Returns the number of milliseconds spent since the module was powered on module get_usbBandwidth Returns the number of USB interfaces used by t
10. Returns the hardware release version of the module function get_productRelease function get_productRelease function get_productRelease int get_productRelease int productRelease function get_productRelease LongInt function get_productRelease As Integer int get_productRelease int get_productRelease def get_productRelease YModule target get_productRelease Returns an integer corresponding to the hardware release version of the module On failure throws an exception or returns Y_PRODUCTRELEASE_INVALID YModule www yoctopuce com 171 21 High level API Reference module get_rebootCountdown YModule module rebootCountdown Returns the remaining number of seconds before the module restarts or zero when no reboot has been scheduled function get_rebootCountdown function get_rebootCountdown function get_rebootCountdown int get_rebootCountdown int rebootCountdown function get_rebootCountdown Longint function get_rebootCountdown As Integer int get_rebootCountdown int get_rebootCountdown def get_rebootCountdown 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 Y_REBOOTCOUNTDOWN_INVALID 172 www yoctopuce com 21 High level API Reference modu
11. YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code YDataLogger www yoctopuce com 241 21 High level API Reference datalogger get_advertisedValue YDataLogger datalogger advertisedValue Returns the current value of the data logger no more than 6 characters function get_advertisedValue function get_advertisedValue function get_advertisedValue string get_advertisedValue NSString advertisedValue function get_advertisedValue string function get_advertisedValue As String string get_advertisedValue String get_advertisedValue def get_advertisedValue Y DataLogger target get_advertisedValue Returns a string corresponding to the current value of the data logger no more than 6 characters On failure throws an exception or returns Y_ADVERTISEDVALUE_INVALID 242 www yoctopuce com 21 High level API Reference datalogger get_autoStart YDataLogger datalogger autoStart Returns the default activation state of the data logger on power up function get_autoStart function get_autoStart function get_autoStart Y_AUTOSTART_enum get_autoStart Y_AUTOSTART_enum autoStart function get_autoStart Integer function get_autoStart As Integer int get_autoStart int get_autoStart def get_autoStart YDataLogger target get_autoStart Returns either Y_AUTOSTART_OFF o
12. lt application lt activity android name MainActivity gt lt intent filter gt lt action android name android intent action MAIN gt lt action android name android hardware usb action USB DEVICE ATTACHED gt lt category android name android intent category LAUNCHER gt lt intent filter gt lt meta data android name android hardware usb action USB DEVICE ATTACHED android resource xml device filter gt 7 E lt activity gt lt application gt lt manifest gt 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 vendorld and devicelD in decimal The following example runs the application as soon as a Yocto Relay or a YoctoPowerRelay is connected You can find the vendorlID and the devicelD of Yoctopuce modules in the characteristics section of the documentation lt xml version 1 0 encoding utf 8 gt lt resources gt lt usb device vendor id 9440 product id 12 gt lt usb device vendor id 9440 product id 13 gt lt resources gt www yoctopuce com 97 18 Using the Yocto Volt with Android 18 5 Control of the Voltage function A few lines of code are enough to use a Yocto Volt Here is the skeleton of a Java code snippet to use the Voltage function aaa Retrieving the object representing the module connected here locally by USB YAPI EnableUSBHost this
13. sensorDC yFindVoltage serial voltagel sensorAC yFindVoltage serial voltage2 if sensorDC isOnline document getHElementById msg value document getElementById DC value sensorDC get_currentValue document getElementById AC value sensorAC get_currentValue else document getHlementById msg value Module not connected setTimeout refresh 500 gt OCR TEN lt HEAD gt lt BODY onload refresh gt Module to use lt input id serial gt lt input id msg style color red border none readonly gt lt br gt Current voltage DC lt input id DC size 5 readonly gt v AC lt input id AC size 5 readonly gt v lt BODY gt lt HTML gt 9 3 Control of the module part 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 lt HTML gt lt HEAD gt lt TITLE gt Module Control lt TITLE gt lt SCRIPT type text javascript src yocto_api js gt lt SCRIPI gt lt SCRIPT language javascript1l 5 type text JavaScript gt a Use explicit error handling rather than exceptions yDisableExceptions Setup the API to use the VirtualHub on local machine if yRegisterHub http 127 0 0 1 4444 YAPI_ SUCCESS www yoctopuce com 33 9 Using Yocto Volt with Javascript alert 4 Cannot cContacke
14. 127 0 0 1 4444 YAPI_ SUCCESS alent tHiGannot contact Virecua l Hubroen Ia PO Oller var module function refresh var serial document getElementBylId serial value if serial Detect any conected module suitable for the demo module yFirstModule nextModule if module serial modulenge Le serialNumper i document getElementBylId serial value serial module yFindModule serial if module isOnline document getElementById msg value document getElementById curName value module get_logicalName else document getHElementById msg value Module not connected setTimeout refresh 1000 function save var newname document getElementBylId newName value if yCheckLogicalName newname alert invalid logical name Ee era module set_logicalName newname module saveToFlash gt lt SCRIPT gt lt HEAD gt lt BODY onload refresh gt Module to use lt input id serial gt lt input id msg style color red border none readonly gt lt br gt Current name lt input id curName readonly gt lt br gt New logical name lt input id newName gt lt a href javascript save gt Save lt a gt lt BODY gt lt HTML gt 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
15. 3 If your callback requires authentication enter credentials here Digest authentication is recommended but Basic authentication works as well Username yocto Password CON 4 Setup the desired frequency of notifications No less than 3 seconds between two notification But notify after 600 seconds in any case 5 Press on the Test button to check your parameters 6 When everything works press on the OK button Test fox Cancel 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 Usage 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 inelude yoctonap phpm yRegisterHub callback The remainder of the code stays strictly identical On the Virtua Hub 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 Virtua Hub Indeed it requires the information posted by the VirtualHub to
16. 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 yDisableExceptions 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 Y STATE INVALID value a get _currentValue method returns a Y 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 infor
17. Console WriteLine press Ctrl C to exit ySleep 1000 errmsg End While End Sub End Module www yoctopuce com 65 13 Using Yocto Volt with Visual Basic NET 13 4 Control of the module part 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 Imports System 10 Imports System Environment Module Modulel Sub usage Console WriteLine usage demo lt serial or logical name gt ON OFF End End Sub Sub Main Dim argv As String System Environment GetCommandLineArgs Dim errmsg As String Dim m As ymodule Te yeeie tery USDOL ETAn lt 7 VARIT ol Clo 5 Mren Console WriteLine RegisterHub error errmsg End End If If argv Length lt 2 Then usage m yFindModule argv 1 REM use serial or logical name rf m isOnline Li aroy tengih gt 2 Then Et axgyv 2 ON Then m set_beacon Y_ BEACON ON If argv 2 OFF Then m set_ beacon Y_ BEACON OFF End TE Console WriteLine serial Wo moget ser taliNumbers Console WriteLine logical name m get_logicalName Console WriteLine luminosity n Str m get_luminosity Console Write beacon my Ee miget beacon YeBEACONsON ihen Console WriteLine ON Else Console WriteLine OFF ENATTE Console WriteLine upTime u Stem get uprimne 7000 see ConsolenWritehin
18. android os Handler android view View android widget AdapterView android widget AdapterView OnItemSelectedListener android widget ArrayAdapter android widget Spinner android widget TextView COMA C EODUCEC ERY OC EOME TAYARI com yoctopuce YoctoAPI YAPI Exception com Voc topuce YoctoAPl yY Module com YOCtCOpuce YOCtOAPL YVoltage class GettingStarted Yocto Volt extends Activity implements OnItemSelectedListener private ArrayAdapter lt String gt aa private Sievers Sree Vp private Handler handler null Override public void onCreate Bundle savedInstanceState super onCreate savedInstanceState setContentView R layout gettingstarted_yocto volt Spinner my spin Spinner findViewById R id spinner1 my spin setOnItemSelectedListener this aa new ArrayAdapter lt String gt this android R layout simple spinner item aa setDropDownViewResource android R layout simple spinner dropdown item my spin setAdapter aa handler new Handler Override protected void onStart super onStart cry A aa clear YAPI EnableUSBHost this YAPI RegisterHub usb YModule module YModule FirstModule while module null if module get_productName equals Yocto Volt String serial module get_serialNumber aa add serial module module nextModule Bice QONEI IASC oEslem 4 aa e prnestackirace gt notifyDat
19. f registerTimedReportCallback periodicCallback As for value change callbacks each module function can thus have its own distinct timed report callback Generic callback functions It is sometimes desirable to use the same callback function for various types of sensors e g for a generic sensor graphing application This is possible by defining the callback for an object of class YSensor rather than YVoltage Thus the same callback function will be usable with any subclass of YSensor and in particular with YVoltage With the callback function you can use the method get _unt to get the physical unit of the sensor if you need to display it A complete example You can find a complete example implemented in your favorite programming language in the Examples Prog EventBased directory of the corresponding library 19 2 The data logger Your Yocto Volt is equipped with a data logger able to store non stop the measures performed by the module The maximal frequency is 100 times per second i e 100 s and the minimal frequency is 1 time per hour i e 1 h When the frequency is higher than or equal to 1 s the measure represents an instant value When the frequency is below the measure will include distinct minimal maximal and average values based on a sampling performed automatically by the device The data logger flash memory can store about 500 000 instant measures or 125 000 averaged measures When the memory is about to be
20. layout addView tx module module nextModule PCA woh VAP IEx cept ionien e printStackTrace Override protected void onStart SUPCE Onsite i trey 4 YAPI EnableUSBHost this YAPI RegisterHub usb cach YAP TOEx cep on 2 er print otackutradcei refreshInventory null Override protected void onStop super onStop YAPI FreeAPI 104 www yoctopuce com 18 Using the Yocto Volt with Android 18 7 Error handling 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 Ja
21. 12 Using Yocto Volt with Objective C oo cece ees tessesneeseeseesnesteeneeneenss 57 12 1 Controkot the Vollage function sisser niche eee 57 12 2 Control of the Module part sinsir ee e eaaa ia Apasia 59 apee AA LOTET ITAN IRA e E E A A E bac spat A E E E A 61 13 Using Yocto Volt with Visual Basic NET oo eects 63 ASEM INSTA EON cesses Seek crete le os eset erat ceca tat tay e a tanec vet heavier tetena stat EG 63 13 2 Using the Yoctopuce API in a Visual Basic project ooo eee eeseeeeeeeeeeeeeeneeeeeeneeeeteneaeees 63 13 3 Control of the Voltage function oie eee ce eene eee eeeeeeeeeaeeeteeaeeeeteaeeeeseaeeeeeeaeeeeeeaeaeesegaeeey 64 13 4 Control of the module part 2 82 a ea a raea ae Ni Wa ann ea Aa eats iadaaa 66 13 5 Error handling seug 2 leccedeeateet eaii hecer eens ested cs i EEE aa E ES eed A EAEEREN EE A aeni aa aiia 68 14 Using Yocto Volt with CH occ ccs es eeesesseeseeseeseeseessessesseneesseseeseesneeee 69 TAS AINStallatiOny haieri ia A uae a a e e EA e eee ae 69 14 2 Using the Yoctopuce API in a Visual C project esssessessseesriiseerirerrirsriiresrrirserrrnerrnenes 69 14 3 Control of the Voltage FUNCTION eee ceeceeceeeeeeeeeeeeeeeeeeeeeeeeaaeeeeeeeseaaaeeeeeesenaaeeeeeesneneaaees 70 14 4 Control of the module Part 2 ceeeeececeeeeeeeeeeeneeeeeeeeeeaeeeeeeeeeaaeeeeeeseseceeeeeeeeeeeeeeeeeenie 72 14 5 Error Nandling scsccsccscecc iesecl sp ateseeeciveess cocoate deevasaaucevdycechseaacesdeavessauevedecheeshadeee
22. CECI T CRESTELE YAPI Sleep 1000 NULL r a few really important lines in this example We will look at them in details et yocto_voltage h These two import files provide access to the functions allowing you to manage Yoctopuce modules yocto api h must always be used yocto voltage h is necessary to manage modules containing a voltage sensor such as Yocto Volt yRegisterHub The yRegist be looked for erHub function initializes the Yoctopuce API and indicates where the modules should 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 58 www yoctopuce com 12 Using Yocto Volt with Objective C yFindVoltage The yFindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once YVoltage voltage yFindVoltage VOLTAGE1 123456 voltagel YVoltage voltage yFindVoltage VOLTAGE1 123
23. View android widget android widget android widget android widget android widget android widget android widget AdapterView AdapterView OnItemSelectedListener ArrayAdapter EditText Spinner TextView Toast com yoctopuce YoctoAPI YAPI com yoctopuce YoctoAPI YAPI Exception com yYocLtopuce YoctoAPl Y Module Class SaveSettings extends Activity implements OnitemSelectedlistener private ArrayAdapter lt String gt aa private YModule module null Override public void onCreate Bundle savedInstanceState super onCreate savedInstanceState setContentView R layout savesettings Spinner my spin Spinner findViewById R id spinner1 my spin setOnItemSelectedListener this aa new ArrayAdapter lt String gt this android R layout simple spinner item aa setDropDownViewResource android R layout simple spinner dropdown_item my spin setAdapter aa Override protected void onStart super onStart try 102 www yoctopuce com 18 Using the Yocto Volt with Android aa clear YAPI EnableUSBHost this YAPI RegisterHub usb YModule r YModule FirstModule while r null String hwid r get_hardwarelId aa add hwid r r nextModule Gabehe WAP TE Vhxcep rane er Pprinestackiracei gt I refresh Spinner with detected relay aa notifyDataSetChanged Override protected void onStop Super ONsi
24. a YModule object allowing you to drive the module or get additional information on the module www yoctopuce com 151 21 High level API Reference YModule FirstModule YModule yFirstModule Starts the enumeration of modules currently accessible function yFirstModule nodejs function FirstModule function yFirstModule cpp _ YModule yFirstModule m YModule yFirstModule function yFirstModule TYModule function yFirstModule As YModule YModule FirstModule YModule FirstModule def 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 152 www yoctopuce com 21 High level API Reference module describe Returns a descriptive text that identifies the module function describe function describe function describe string describe NSString describe function describe string function describe As String string describe String describe def describe The text may include either the logical name or the serial number of the module YModule Returns a string that describes the module www yoctopuce com 153 21 High level API Reference module gt download YModule Downloads the specified built in file and returns a binary buffer with it
25. 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 46 www yoctopuce com 10 Using Yocto Volt with PHP Common issues 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 Limitations 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 Virtua Hub but it is at least of a few seconds in the best case The HTTP callback Y
26. module gt set_userData data Stores a user context provided as argument in the userData attribute of the function module triggerFirmwareUpdate secBeforeReboot Schedules a module reboot into special firmware update mode module wait_async callback context Waits for all pending asynchronous commands on the module to complete and invoke the user provided callback function 150 www yoctopuce com 21 High level API Reference YModule FindModule YModule yFindModule Allows you to find a module from its serial number or from its logical name function yFindModule func function FindModule func function yFindModule func YModule yFindModule string func YModule yFindModule NSString func function yFindModule func string TYModule function yFindModule ByVal func As String As YModule YModule FindModule string func YModule FindModule String func def FindModule 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 Parameters func a string containing either the serial number or the logical name of the desired module Returns
27. problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang 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 yDisableExceptions 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 Y STATE INVALID value a get _currentValue method returns a Y 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 th
28. style color red border none readonly gt lt br gt lt span id data gt lt span gt lt BODY gt lt HTML gt 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 Changing the module settings 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 lt HTML gt lt HEAD gt lt TITLE gt Change module settings lt TITLE gt lt SCRIPT type text javascript srce yocto api js gt lt SCRIPT gt lt SCRIPT language javascript1l 5 type text JavaScript gt A 34 www yoctopuce com 9 Using Yocto Volt with Javascript Use explicit error handling rather than exceptions yDisableExceptions Setup the API to use the VirtualHub on local machine if yRegisterHub http
29. while the voltage2 input corresponds to the AC voltage component The typical accuracy of the DC measure is 0 01V or 0 5 percent while the precision of the AC measure is 0 1V or 3 percent for frequencies between 30Hz and 80Hz 18 www yoctopuce com 7 Programming general concepts 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 usbBandwidth Enumerated modifiable voltage Voltage voltage2 Voltage attribute type modifiable logicalName String modifiable advertisedValue String read only unit String read only currentValue Floating point number read only lowestValue Floating point number modifiable highestValue Floating point number modifiable currentRawValue Floating point number read only logFrequency Frequency modifiable reportFrequency Frequency modifiable calibrationParam 16 bit word array modifiable resolution Floating point number modifiable dataLogger DataLogger attribute type modifiable logicalName String modifiable advertisedValue String read only currentRuniIndex Integer
30. yUpdateDeviceList is running You will have to call this function on a regular basis Parameters object an object that must follow the procol YAP IDelegate or nil 142 www yoctopuce com 21 High level API Reference YAPI SetTimeout YAPI ySetTimeout Invoke the specified callback function after a given timeout function ySetTimeout callback ms_timeout arguments function SetTimeout callback ms_timeout arguments This function behaves more or less like Javascript set Timeout 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 arguments 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 www yoctopuce com 143 21 High level API Reference YAPI Sleep YAPI ySleep Pauses the execution flow for a specified duration function ySleep ms_duration errmsg function Sleep ms_duration errmsg function ySleep ms_duration a
31. 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 e If your code catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang 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 yDisableExceptions 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
32. 1 Getling ready Airain dian neil een een at Cei TAE ri EA EANA deinen 31 9 2 Control of the Voltage FUNCTION oo ee ee ce eeeteeeeenneeeteeeeeee tenes eeeaeeeeteaeaeeseaaaeeseaaeesennaeeeenaaes 31 9 3 Control of the MOCUIe Part ooo eee cece ee eeneeeeeeeeeeeeeaeeeeeeaeeeeeeaaeeeeeeeeeeseeeeeseieeeetsneeeeenaes 33 QA Error NANANA e aa T a raa a a aE aE aaa a arr Aaa a A E anain Aaa aA aSa inidan 36 10 Using Yocto Volt with PHP ooo cs ce ceeeesneseeseeseeneseessnneseeseeneeeeenees 39 TOA2 GOING TOAGY lt lt 2hs 2 d caccpecnedecahsceedciedacseneceudSccishindedsdecaseasedsasenhabsucadsdscaveesbissusniiasdaitiedtesdesey 39 10 2 Control of the Voltage function oe eee ce eeneeeeeete etree aeeeeteeeeeteaeeeeseaeeeeseaeeeeseeaeeseaaeeey 39 10 34 Control OPthe MOduUIe part pinn a behaves pedir see 41 10 4 HTTP callback API and NAT filters oe eeeeeeeeeeeeeeneeeeeeeneeeeeeaeeeeeeaeeeeeeaeaeeseaaeetenaeeeeeas 44 10 5 Erromnandling seins wns in ape eee aes 47 11 Using Yocto Volt with Ce oie cesees cesses sesseesecsestesseetesneesseseeseesteanesneanse 49 11 1 Control of the Voltage function occ ce cence eter cette nee eeecneeee senate eseaeeeeeeaeeeeeeeaeeeeaaeees 49 1122 Control ot the module part 5 2 ae eA ae acess A A das cate Sag Sens hen sano sous 51 T8 Error handling xesc0set see Genii ede inv oa A diaesein Aleit eel ees 54 11 4 Integration variants for the C Yoctopuce library ccccccceeeceeeeeeeeeeeeeeneeeeeeeeeeeeeeeeeees 54
33. 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 18 4 Activating the USB port under Android 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 lt uses feature android name android hardware usb host gt tag in the manifest section lt manifest gt lt uses feature android name android hardware usb host gt lt manifest gt 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 2 Yoctohubs are a plug and play way to add network connectivity to your Yoctopuce devices more info on hittp www yoctopuce com EN products category extensions and networking 96 www yoctopuce com 18 Using the Yocto Volt with Android it stays connected To
34. As String string describe String describe def 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 relayl RELAYLO1 123456 relayl if the module is already connected or Relay BadCustomeName relayl 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 data logger ex Relay MyCustomName relayl RELAYLOI1 123456 relayl 240 www yoctopuce com 21 High level API Reference datalogger forgetAllDataStreams Clears the data logger memory and discards all recorded data streams function forgetAllDataStreams function forgetAllDataStreams function forgetAllDataStreams int forgetAllDataStreams int forgetAllDataStreams function forgetAllDataStreams Longint function forgetAllDataStreams As Integer int forgetAllDataStreams int forgetAllDataStreams def forgetAllDataStreams YDataLogger target forgetAllDataStreams This method also resets the current run index to zero Returns
35. As String string get_unit String get_unit def get_unit Returns a string that represents a physical unit On failure throws an exception or returns Y_UNIT_INVALID YDataSet www yoctopuce com 281 21 High level API Reference dataset loadMore YDataSet Loads the the next block of measures from the dataLogger and updates the progress indicator is _ function loadMore node js function loadMore php function loadMore cpp _ int loadMore int loadMore pas _ function loadMore LongInt ve function loadMore As Integer cs__ int loadMore java _ int loadMore def loadMore Returns an integer in the range 0 to 100 percentage of completion or a negative error code in case of failure On failure throws an exception or returns a negative error code 282 www yoctopuce com 21 High level API Reference dataset loadMore_async YDataSet Loads the the next block of measures from the dataLogger asynchronously function loadMore_async callback context function loadMore_async callback context Parameters callback callback function that is invoked when the w The callback function receives three arguments the user specific context object the YDataSet object whose loadMore_async was invoked the load result either the progress indicator 0 100 or a negative error code in case of failure context user specific objec
36. Changes the current UTC time reference used for recorded data datalogger set_userData data Stores a user context provided as argument in the userData attribute of the function datalogger wait_async callback context Waits for all pending asynchronous commands on the module to complete and invoke the user provided callback function www yoctopuce com 237 21 High level API Reference YDataLogger FindDataLogger YDataLogger yFindDataLogger Retrieves a data logger for a given identifier function yFindDataLogger func node js function FindDataLogger func function yFindDataLogger func YDataLogger yFindDataLogger string func YDataLogger yFindDataLogger NSString func function yFindDataLogger func string TYDataLogger function yFindDataLogger ByVal func As String As YDataLogger Y DataLogger FindDataLogger string func YDataLogger FindDataLogger String func def FindDataLogger func The identifier can be specified using several formats e FunctionLogicalName e ModuleSerialNumber Functionldentifier e ModuleSerialNumber FunctionLogicalName e ModuleLogicalName Functionldentifier e ModuleLogicalName FunctionLogicalName This function does not require that the data logger is online at the time it is invoked The returned object is nevertheless valid Use the method YDat aaLogger isOnline to test if the data logger is indeed online at a given time In case of ambiguity when looking
37. FloatToStr sensorDC get_currentValue v We neee Serle cielo stm SensorAGrge t PeU renea aE Writeln press GET CREO ESEE ySleep 1000 errmsg until false end There are only a few really important lines in this sample example We will look at them in details yocto_api and yocto_voltage These two units provide access to the functions allowing you to manage Yoctopuce modules yocto_ api must always be used yocto_ voltage is necessary to manage modules containing a voltage sensor such as Yocto Volt 78 www yoctopuce com 15 Using Yocto Volt with Delphi yRegisterHub 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 yFindVoltage The yFindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defi
38. If an error happens while you try to access a module the library throws an exception In this case there are three possibilities e If your code catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang 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 yDisableExceptions 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 Y STATE INVALID value a get _currentValue method returns a Y 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 36 www yoctopuce com 9 Using Yocto Volt
39. 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 lt script type text javascript src yocto_api js gt lt script gt var yoctolib require yoctolib var YAPI yoctolib YAPI var YModule yoctolib YModule require_once yocto_api php include yocto_api h import yocto_api h uses yocto_api yocto_api vb yocto_api cs import com yoctopuce YoctoAPI YModule from yocto_api import Global functions yFindModule func Allows you to find a module from its serial number or from its logical name yFirstModule Starts the enumeration of modules currently accessible YModule methods module gt 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 gt functionCount Returns the number of functions beside the module interface available on the module module functionld 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 functionValue functionIndex Retrieves the advertised value of the nth function on the module module get_beacon Returns the state of the localization beacon module get_errorMessage
40. Moreover the measure includes precise timestamps which makes it possible to use timed reports for a time based graph even when not handled immediately static void periodicCallback YVoltage fct YMeasure measure Console Writeline fct get hardwareld measure get_averageValue Setting up a timed report callback The callback is set up for a given Voltage function with the help of the registerTimedReportCallback method The callback will only be invoked once a callback frequency as been set using set reportFrequency which defaults to timed report callback turned off The frequency is specified as a string same as for the data logger by specifying the number of calls per second s per minute m or per hour h The maximal frequency is 100 times per second i e 100 s and the minimal frequency is 1 time per hour i e 1 h When the frequency is higher than or equal to 1 s the measure represents an instant value When the frequency is below the measure will include distinct minimal maximal and average values based on a sampling performed automatically by the device The following example sets up a timed report callback 4 times per minute for t he first available Voltage function YVoltage f YVoltage FirstVoltage f set_reportFrequency 4 m 1 The value passed as parameter is the same as the value returned by the get_advertisedValue method www yoctopuce com 109 19 Advanced programming
41. Native 22 95 NET 63 nextDataLogger YDataLogger 262 nextModule YModule 181 nextVoltage YVoltage 224 O Objective C 57 Optional 3 P Paradigm 17 Platforms 292 Port 96 Porting 122 Power 16 Preparation 77 PreregisterHub YAPI 134 Prerequisites 1 Presentation 5 Programming 17 24 107 Project 63 69 Python 83 R reboot YModule 182 Recorded 271 Reference 123 RegisterDeviceArrivalCallback YAPI 135 RegisterDeviceRemovalCallback YAPI 136 RegisterHub YAPI 137 RegisterHubDiscoveryCallback YAPI 138 RegisterLogFunction YAPI 139 registerTimedReportCallback YVoltage 225 registerValueCallback YDataLogger 263 registerValueCallback YVoltage 226 revertFromFlash YModule 183 S saveToFlash YModule 184 SelectArchitecture YAPI 140 Sensor 112 Sequence 271 Service 22 set_autoStart YDataLogger 264 set_beacon YModule 185 set_highestValue YVoltage 227 set_logFrequency YVoltage 228 set_logicalName YDataLogger 265 set_logicalName YModule 186 set_logicalName YVoltage 229 set_lowestValue YVoltage 230 set_luminosity YModule 187 set_recording YDataLogger 266 set_reportFrequency YVoltage 231 set_resolution YVoltage 232 set_timeUTC YDataLogger 267 set_usbBandwidth YModule 188 set_userData YDataLogger 268 set_userData YModule 189 set_userData YVoltage 233 SetDelegate YAPI 141 SetTimeout YAPI 142 Sleep YAPI 143 Source 83 Start 24 T Test 11 triggerFirmwareUpdate YModule 190 Troubl
42. 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 164 www yoctopuce com 21 High level API Reference module gt get_lastLogs module gt lastLogs Returns a string with last logs of the module function get_lastLogs function get_lastLogs function get_lastLogs string get_lastLogs NSString lastLogs function get_lastLogs string function get_lastLogs As String string get_lastLogs String get_lastLogs def get_lastLogs YModule target get_lastLogs This method return only logs that are still in the module Returns a string with last logs of the module YModule www yoctopuce com 165 21 High level API Reference module gt get_logicalName YModule module gt logicalName Returns the logical name of the module function get_logicalName function get_logicalName function get_logicalName string get_logicalName NSString logicalName function get_logicalName string function get_logicalName As String string get_logicalName String get_logicalName def get_logicalName YModule target get_logicalName Returns a string corresponding to the logical name of the module On failure throws an exception or returns Y_LOGICALNAME_INVALID 166 www yoctopuce com 21 High level API Reference module gt get_luminosity Y
43. Yocto Volt with Android oo cece cee tec cee eeseeseeeeetesteeeesteneenes 95 18 1 Native access and VirtualHub oo eee ec eenee ee eene eterna nee eeeaaeeeeeeaeeeeseaeeeeeeaeeeeseaeaeeseeaeees 95 18 2 Getting teady sernir tiae annae Wold een ire i ceed a ea AE 95 18 3 Compati Diy e aae a ae raa aa Ea T aea ae aa aeaa iia a Ta daa aa aa aia aa Ea a delana 95 18 4 Activating the USB port under Android o oo eeeeceeeeneeeeeeeeeeeeeneeeeseaeeeeeeaeeeeeeeaeeseaeeeeeeas 96 18 5 Control of the Voltage FUNCTION siiin e ae aaae Tei egaa apera 98 18 6 Control of the mod le Part oo ceeeeeeeeeseeeeeeeeeeneneeeeeseeneesaneceseaneeeenaneeeensaeeneneseeneesaes 100 18 75 ErOnMANGIING AWA canna in ee a ee i ae ae le ede Lats 105 19 Advanced programming oe ec rere 107 19 1 Event programming ieren dietitian ee nindevieneeeiinebtieneradleevesune 107 19 2 The datalogger tiws E ETTE Rene Rs Re Re RAR ae a ee 110 19 3 SenSor calibration oiiire eag ea a iaaa a e aee a eeii 112 20 Using with unsupported languages 2 cece ccc cee teeeeeeeeeeteeteeneeneees 117 20 1 Command lines areri aatri ent Eiaa dee at eels AAEE eerie nent 117 20 2 Vina eta GET edt le caicccteece aaae eea le cha ich e ee eaa 117 20 3 Using dynamic lirare S senine se eceheies ieee neh avendeessigeeecves N A aai i 119 20 4 Porting the high level library oe eee eeeeeseeeeeeeeeeeeneneeeesaneeeesaneeeesaeeenesaeeneneeenesseneneesas 122 21 High level API Reference oni cc cee ce
44. and in working order 4 Remember to change the filter of the selection window otherwise the DLL will not show 70 www yoctopuce com 14 Using Yocto Volt with C get_currentValue The get_currentValue method of the object returned by YVoltage FindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts A real example Launch Microsoft Visual C and open the corresponding sample project provided in the directory Examples Doc GettingStarted Yocto Volt 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 using System using ovstem Collections Generic using System Ling using System Text namespace ConsoleApplicationl class Program static void usage string execname System AppDomain CurrentDomain FriendlyName Console WriteLine Usage Console WriteLine execname lt serial_ number gt Console WriteLine execname lt logical_ name gt Console WriteLine execnamet any System Threading Thread Sleep 2500 Environment Exit 0 static void die string msg Console WriteLine msg check USB cable Environment Exit 0 static void Main string args string errmsg string target YVoltage sensor YVoltage sensorDC null YVoltage sensor
45. as in the exceptions when they are active 62 www yoctopuce com 13 Using Yocto Volt with Visual Basic NET 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 site 13 1 Installation Download the Visual Basic Yoctopuce library from the Yoctopuce web site 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 13 2 Using the Yoctopuce API in a Visual Basic project 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 modules 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 Configuring a Visual Basic project The following indications are provided for Vi
46. be stored 190 www yoctopuce com 21 High level API Reference module triggerFirmwareUpdate Schedules a module reboot into special firmware update mode function triggerFirmwareUpdate secBeforeReboot function triggerFirmwareUpdate secBeforeReboot function triggerFirmwareUpdate secBeforeReboot int triggerFirmwareUpdate int secBeforeReboot int triggerFirmwareUpdate int secBeforeReboot function triggerFirmwareUpdate secBeforeReboot Longint Longint function triggerFirmwareUpdate As Integer int triggerFirmwareUpdate int secBeforeReboot int triggerFirmwareUpdate int secBeforeReboot def triggerFirmwareUpdate secBeforeReboot YModule target triggerFirmwareUpdate secBeforeReboot YModule 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 www yoctopuce com 191 21 High level API Reference module wait_async YModule Waits for all pending asynchronous commands on the module to complete and invoke the user provided callback function function wait_async callback context function 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 m
47. cable YAPI FreeAPI 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 Changing the module settings 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 import com yoctopuce YoctoAPI public class Demo HUSTLERS tatie vord man otci ag eae s try setup the API to use local VirtualHub TWAIPIE 6 INGie alsheSualenble MGL29 0S 5 INN catch YAPT Exception ex SVSECMOUE PLrRINEIME Cannon Contact VilecuallHub one 277 0n Ores Ghee ex getLocalizedMessage System out printin Ensure that the VirtualHub application is running System exit 1 if args length 2 System out printin usage demo lt serial
48. com 57 12 Using Yocto Volt with Objective C NSError YVoltage YVoltage YVoltage YModule 12 arge usag autorel NSSt error sensor sensorAC sensorDC m at e easepool ring target NSString stringWithUTF8String argv 1 Setup the API to use local USB devices abi wae l el YAPI RegisterHub usb amp error YAPI SUCCESS NSLog RegisterHub error error localizedDescription return 1 target isEqualToString any retreive any voltage sensor can be AC or DC sensor YVoltage FirstVoltage if sensor NULL NSLog No module connected check USB cable return 1 se sensor YVoltage FindVoltage target stringByAppendingString voltagel we need to retreive both DC and AC voltage from the device KARI i stringByAppe stringByAppe Gul whil return 0 There are only yocto_api h sensor isOnline m sensor module sensorDC YVoltage FindVoltage m serialNumber ndingString voltagel sensorAC YVoltage FindVoltage m serialNumber ndingString voeltage2 se NSLog No module connected check USB cable return i ey f im is niines NSLog No module connected check identification and USB cable return 17 NSLog Voltage DC Sf v sensorDC currentValue NSLog AC Sf v SensorAC currentValue NSlogi Gil press
49. eil Ss Us Le args lengen gt 0 serial args 0 else YVoltage tmp YVoltage FirstVoltage if tmp null 90 www yoctopuce com 17 Using the Yocto Volt with Java System out println No module connected check USB cable System exit 1 try 4 serial tmp module get_serialNumber je eatea CAET ee piston nes i System out println No module connected check USB cable System exit 1 we need to retreive both DC and AC voltage from the device YVoltage sensorDC YVoltage FindVoltage serial voltagel YVoltage sensorAC YVoltage FindVoltage serial voltage2 while true tery System out printim Mes VY o gt Seinserae get leurcenNalue Onn Yay WP System out p Elmer lm UAC a SonsSOLAG gereu renale System out PrIntin A press EEr E tor exiit YAPI Sleep 1000 icatch YARD Excepicdion ex i 4 System out println Module sensorAC describe is not connected check identification and USB cable break NOME pls e eey NEE Qe 17 3 Control of the module part 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 import com yoctopuce YoctoAPI import java util logging Level import java util logging Logger public class Demo public static void main String args try setup the API t
50. errmsg int yapiGetDeviceInfo int devdesc yDeviceSt infos char errmsg 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 120 www yoctopuce com 20 Using with unsupported languages 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 bytes Pescription 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
51. for a data logger 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 func a string that uniquely characterizes the data logger Returns a YDataLogger object allowing you to drive the data logger 238 www yoctopuce com 21 High level API Reference YDataLogger FirstDataLogger yFirstDataLogger Starts the enumeration of data loggers currently accessible function yFirstDataLogger function FirstDataLogger function yFirstDataLogger YDataLogger yFirstDataLogger YDataLogger yFirstDataLogger function yFirstDataLogger TYDataLogger function yFirstDataLogger As YDataLogger YDataLogger FirstDataLogger YDataLogger FirstDataLogger def FirstDataLogger YDataLogger Use the method YDataLogger nextDataLogger to iterate on next data loggers Returns a pointer to a YDataLogger object corresponding to the first data logger currently online or a null pointer if there are none www yoctopuce com 239 21 High level API Reference datalogger describe YDataLogger Returns a short text that describes the data logger in the form TYPE NAME SERIAL FUNCTIONID is function describe node js function describe php function describe string describe NSString describe function describe string function describe
52. function set_userData data function set_userData data void set_userData void data void setUserData void data procedure set_userData data Tobject procedure set_userData ByVal data As Object void set_userData object data void set_userData Object data def 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 www yoctopuce com 269 21 High level API Reference datalogger wait_async YDataLogger Waits for all pending asynchronous commands on the module to complete and invoke the user provided callback function function wait_async callback context function 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 270 www yoctopuce com 21 High level API Reference 21 5 Recorded data sequence YDataSet objects make it possible to retrieve a set of recorded measures for a given sensor anda specified time interval They can be used
53. 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 include lt iostream gt iMAC UGS eyot okap hi using namespace std ime Main int large const char argi SEE LAG errmsg Setup the API to use local USB devices if yRegisterHub usb errmsg YAPI SUCCESS corri c lt Wiley pieiecueltible Gieideiay lt lt Giciameye lt lt eialelll 5 return 1 cout lt lt Device list lt lt endl YModule module yFirstModule while module NULL couci lt modulles germsenicl Numa ci le cout lt lt module gt get_productName lt lt endl module module gt nextModule www yoctopuce com 53 11 Using Yocto Volt with C return 0 11 3 Error handling 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 prov
54. is updated persistentSettings State of persistent module settings loaded from flash memory modified by the user or saved to flash memory luminosity 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 beacon Activity of the localization beacon of the module upTime Time elapsed since the last time the module was powered on usbCurrent Current consumed by the module on the USB bus in milli amps rebootCountdown Countdown to use for triggering a reboot of the module usbBandwidth Number of USB interfaces used by the device If this parameter is set to DOUBLE the device can send twice as much data but this may saturate the USB hub Remember to call the saveToFlash method and then to reboot the module to apply this setting 7 4 Voltage function interface The Yoctopuce application programming interface allows you to read an instant measure of the sensor as well as the minimal and maximal values observed logicalName Character string containing the logical name of the voltage sensor 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 voltage sensor directly If two volt
55. is updated to reflect the timestamp of the first measure actually found in the dataLogger within the specified range Returns an unsigned number corresponding to the number of seconds between the Jan 1 1970 and the beginning of this data set i e Unix time representation of the absolute time www yoctopuce com 279 21 High level API Reference dataset get_summary YDataSet dataset summary Returns an YMeasure object which summarizes the whole DataSet function get_summary kodes function get_summary php function get_summary YMeasure get_summary YMeasure summary function get_summary TYMeasure function get_summary As YMeasure YMeasure get_summary YMeasure get_summary def get_summary In includes the following information the start of a time interval the end of a time interval the minimal value observed during the time interval the average value observed during the time interval the maximal value observed during the time interval This summary is available as soon as LoadMore has been called for the first time Returns an YMeasure object 280 www yoctopuce com 21 High level API Reference dataset get_unit dataset unit Returns the measuring unit for the measured value function get_unit function get_unit function get_unit string get_unit NSString unit function get_unit string function get_unit
56. isolation the part that measures the voltage is electrically isolated from the USB part This enables the module to measure the voltage of the mains without risking to destroy your computer The Yocto Volt module Yoctopuce thanks you for buying this Yocto Volt 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 Volt is easy to install anywhere and easy to drive from a maximum of programming languages If you are nevertheless disappointed with this module do not hesitate to contact Yoctopuce support By design all Yoctopuce modules are driven the same way Therefore user s guides for all the modules of the range are very similar If you have already carefully read through the user s guide of another Yoctopuce module you can jump directly to the description of the module functions 1 1 Prerequisites In order to use your Yocto Volt module you should have the following items at hand 1 support yoctopuce com www yoctopuce com 1 Introduction A computer Yoctopuce modules are intended to be driven by a computer or possibly an embedded microprocessor You will write the control software yourself according to your needs using the information provided in this manual Yoctopuce provides software libraries to drive its modules for the following operating systems Windows Mac OS X Linux and Android Yoctopuce modules do not require in
57. 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 14 2 Using the Yoctopuce API in a Visual C project 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 modules 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 Configuring a Visual C project 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
58. name Each function can be assigned an arbitrary and persistent logical name this logical name is stored in the flash memory of the module even if this module is disconnected An object corresponding to an Xxx function to which a logical name has been assigned can then be directly found with this logical name and the YXxx FindXxx method Note however that a logical name must be unique among all the connected modules Access by enumeration You can enumerate all the functions of the same type on all the connected modules with the help of the classic enumeration functions FirstXxx and nextXxxx available for each YXxx class Access by hardware name Each module function has a hardware name assigned at the factory and which cannot be modified The functions of a module can also be found directly with this hardware name and the YXxx FindXxx function of the corresponding class Difference between Find and First The YXxx FindXxxx and YXxx FirstXxxx methods do not work exactly the same way If there is no available module YXxx FirstXxxx returns a null value On the opposite even if there is no corresponding module YXxx FindXxxx returns a valid object which is not online but which could become so if the corresponding module is later connected Function handling When the object corresponding to a function is found its methods are available in a classic way Note that most of these subfunctions require the module hosting the function to be connecte
59. negative error code 146 www yoctopuce com 21 High level API Reference YAPI UpdateDeviceList_async yUpdateDeviceList_async Triggers a re detection of connected Yoctopuce modules function yUpdateDeviceList_async callback context function UpdateDeviceList_async callback context YAPI 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 YAP 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 _SUCC ESS if the operation www yoctopuce com 147 21 High level API Reference 21 2 Module control interface This interface is identical for all Yoctopuce USB modules
60. net connected check identitilication and USB cable 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 Listing the modules 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 usr bin python coding utf 8 import os sys ErcOME VOCE Oma Ol importi errmsg YRef Param 86 www yoctopuce com 16 Using the Yocto Volt with Python Setup the API to use local USB devices if YAPI RegisterHub usb errmsg YAPI SUCCESS sys exit init error str errmsg prine Deyrceriiis tii module YModule FirstModule while module is not None print module get_serialNumber tmodule get _productName module module nextModule 16 5 Error handling When you implement a program which must interact with USB module
61. read only timeUTC UTC time modifiable recording On Off modifiable autoStart On Off modifiable clearHistory Boolean modifiable 7 3 Module control interface This interface is identical for all Yoctopuce USB modules It can be used to control the module global parameters and to enumerate the functions provided by each module productName Character string containing the commercial name of the module as set by the factory serialNumber Character string containing the serial number unique and programmed at the factory For a Yocto Volt module this serial number always starts with VOLTAGE1 You can use the serial number to access a given module by software www yoctopuce com 19 7 Programming general concepts logicalName Character string containing the logical name of the module initially empty This attribute can be modified at will by the user Once initialized to an non empty value it can be used to access a given module If two modules with the same logical name are in the same project there is no way to determine which one answers when one tries accessing by logical name The logical name is limited to 19 characters among A Z a z 0 9 and productlid USB device identifier of the module preprogrammed to 27 at the factory productRelease Release number of the module hardware preprogrammed at the factory firmwareRelease Release version of the embedded firmware changes each time the embedded software
62. saturated the oldest measures are automatically erased Make sure not to leave the data logger running at high speed unless really needed the flash memory can only stand a limited number of erase cycles typically 100 000 cycles When running at full speed the datalogger can burn more than 100 cycles per day Also be aware that it is useless to record measures at a frequency higher than the refresh frequency of the physical sensor itself Starting stopping the datalogger The data logger can be started with the set_ recording method YDataLogger 1 YDataLogger FirstDataLogger 1 set_recording YDataLogger RECORDING ON It is possible to make the data recording start automatically as soon as the module is powered on YDataLogger 1 YDataLogger FirstDataLogger l set_autoStart YDataLogger AUTOSTART_ ON IGetumodullel jsavetorilashi i 7 7 do noe forges to save Ene setting Note Yoctopuce modules do not need an active USB connection to work they start working as soon as they are powered on The Yocto Volt can store data without necessarily being connected to a computer you only need to activate the automatic start of the data logger and to power on the module with a simple USB charger Erasing the memory The memory of the data logger can be erased with the forgetAllDataStreams function Be aware that erasing cannot be undone YDataLogger 1 YDataLogger FirstDataLogger i forgetAllDataStreams
63. 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 1 http www microsoft com visualstudio en us products 2010 editions visual csharp express www yoctopuce com EN libraries php 3 The sources of this DLL are available in the C API www yoctopuce com 69 14 Using Yocto Volt with C Then add in the same manner the yapi d11 DLL located in the Sources dl1 directory 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 14 3 Control of the Voltage function A few lines of code are enough to use a Yocto Volt Here is the skeleton of a C code snipplet to use the Voltage function eae string errmsg YVoltage voltage Get access to your device connected locally on USB for instance YAPI RegisterHub usb errmsg voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel Hot plug is easy just check that the device is online if voltage isOnline Use voltage get_currentValue Let s look at these lines
64. the datalogger e When the Yocto Volt is connected to a computer running either the VirtualHub or any application using the Yoctopuce library it will automatically receive the time from this computer e When the Yocto Volt is connected to a YoctoHub Ethernet it will get the time that the YoctoHub has obtained from the network using a server from pool ntp org When the Yocto Volt is connected to a YoctoHub Wireless it will get the time provided by the YoctoHub based on its internal battery powered real time clock which was itself configured either from the network or from a computer e When the Yocto Volt is connected to an Android mobile device it will get the time from the mobile device as long as an app using the Yoctopuce library is launched When none of these conditions applies for instance if the module is simply connected to an USB charger the Yocto Volt will do its best effort to attach a reasonable timestamp to the measures using the timestamp found on the latest recorded measures It is therefore possible to preset to the real time an autonomous Yocto Volt by connecting it to an Android mobile phone starting the data logger then connecting the device alone on an USB charger Nevertheless be aware that without external time source the internal clock of the Yocto Volt might be be subject to a clock skew theoretically up to 0 3 19 3 Sensor calibration Your Yocto Volt module is equipped with a digital sensor calibrat
65. the device serial number and of the hardware identifier of the data logger for example RELAYLO1 123456 relayl1 Returns a string that uniquely identifies the data logger ex RELAYLO1 123456 relay1 On failure throws an exception or returns Y_HARDWAREID_INVALID 252 www yoctopuce com 21 High level API Reference datalogger get_logicalName YDataLogger datalogger logicalName Returns the logical name of the data logger function get_logicalName function get_logicalName function get_logicalName string get_logicalName NSString logicalName function get_logicalName string function get_logicalName As String string get_logicalName String get_logicalName def get_logicalName YDataLogger target get_logicalName Returns a string corresponding to the logical name of the data logger On failure throws an exception or returns Y_LOGICALNAME_INVALID www yoctopuce com 253 21 High level API Reference datalogger get_module YDataLogger datalogger module Gets the YModule object for the device on which the function is located is _ function get_module node js function get_module php_ function get_module YModule get_module YModule module function get_module TYModule function get_module As YModule YModule get_module YModule get_module def get_module If the function cannot be located on any modul
66. 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 Y STATE INVALID value a get _currentValue method returns a Y 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 11 4 Integration variants for the C Yoctopuce library 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 Integration in source format Integr
67. 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 yoctocontrol php The HTTP callback API uses the VirtualHub which initiates the requests Configuration 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 1 Launch a VirtualHub 2 Access its interface usually 127 0 0 1 4444 3 Click on the configure button of the line corresponding to the Virtua Hub itself 4 Click on the edit button of the Outgoing callbacks section Serial Logi
68. to load data points with a progress report When the YDataSet object is instanciated by the get_recordedData function no data is yet loaded from the module It is only when the loadMore method is called over and over than data will be effectively loaded from the dataLogger A preview of available measures is available using the function get_preview as soon as loadMore has been called once Measures themselves are available using function get_measures when loaded by subsequent calls to loadMore This class can only be used on devices that use a recent firmware as YDataSet objects are not supported by firmwares older than version 13000 In order to use the functions described here you should include lt script type text javascript src yocto_api js gt lt script gt var yoctolib require yoctolib var YAPI yoctolib YAPI var YModule yoctolib YModule require_once yocto_api php include yocto_api h import yocto_api h uses yocto_api yocto_api vb yocto_api cs import com yoctopuce YoctoAPI YModule from yocto_api import YDataSet methods dataset get_endTimeUTC Returns the end time of the dataset relative to the Jan 1 1970 dataset get_functionld Returns the hardware identifier of the function that performed the measure without reference to the module dataset get_hardwareld Returns the unique hardware identifier of the function who performed the measures in the form SER
69. to reference your module by software However in the opposite of the serial number the logical name can be modified at will The benefit is to enable you to build several copies of the same project without needing to modify the driving software You only need to program the same logical name in each copy Warning the behavior of a project becomes unpredictable when it contains several modules with the same logical name and when the driving software tries to access one of these modules through its logical name When leaving the factory modules do not have an assigned logical name It is yours to define 2 2 Specific elements The sensor This sensor is an ADS1115IDGST analog to digital converter produced by Texas Instruments Its use does not require any particular precaution besides those linked to electrocution hazards 1 short short short long long long short short short 2 support yoctopuce com 6 www yoctopuce com 3 Electrocution hazards While the Yocto Volt module is perfectly able to manage a 250V voltage we strongly discourage you to work on a voltage high enough to present risks Nevertheless if you decide to override this advice respect these recommendations they may well protect you from an embarrassing nomination to the Darwin Awards 3 1 Use your head your luck won t last forever Don t work if you are tired Brilliant decisions taken at 2 a m tend to lose their shine at first light Do not work under the in
70. using method set_userData function get_userData function get_userData function get_userData void get_userData void userData function get_userData Tobject function get_userData As Object object get_userData Object get_userData def 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 www yoctopuce com 177 21 High level API Reference module gt isOnline YModule Checks if the module is currently reachable without raising any error 5s function isOnline node js function isOnline php function isOnline cpp _ bool isOnline BOOL isOnline pas function isOnline boolean vb function isOnline As Boolean cs _ bool isOnline java boolean isOnline def 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 178 www yoctopuce com 21 High level API Reference module gt isOnline_async YModule Checks if the module is currently reachable without raising any error function isOnline_async callback context function isOnline_async callback context If there are
71. 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 www yoctopuce com 179 21 High level API Reference module load YModule Preloads the module cache with a specified validity duration is__ function load msValidity node js function load msValidity php function load msValidity YRETCODE load int msValidity YRETCODE load int msValidity function load msValidity integer YRETCODE function load ByVal msValidity As Integer As YRETCODE YRETCODE load int msValidity int load long msValidity def 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 f
72. 110 www yoctopuce com 19 Advanced programming Choosing the logging frequency The logging frequency can be set up individually for each sensor using the method set _logFrequency The frequency is specified as a string same as for timed report callbacks by specifying the number of calls per second s per minute m or per hour h The default value is 1 s The following example configures the logging frequency at 15 measures per minute for the first sensor found whatever its type YSensor sensor YSensor FirstSensor Sensoxr set logErequency 15 m To avoid wasting flash memory it is possible to disable logging for specified functions In order to do so simply use the value OFF sensor set_logFrequency OFE Limitation The Yocto Volt cannot use a different frequency for timed report callbacks and for recording data into the datalogger You can disable either of them individually but if you enable both timed report callbacks and logging for a given function the two will work at the same frequency Retrieving the data To load recorded measures from the Yocto Volt flash memory you must call the get _recordedData method of the desired sensor and specify the time interval for which you want to retrieve measures The time interval is given by the start and stop UNIX timestamp You can also specify 0 if you don t want any start or stop limit The get_recordedData method does not return directly am a
73. 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 di DLL to list the connected modules device description structure type yDeviceSt packed record vendorid word deviceid word devrelease Word nbinbterfaces word manufacturer Tarca ile 5 iUS wae Euaisalelnener productname Tarca MOG aA Tene ans ehar serial ar cay ils SRo ansieae logicalname Tar cay Onm Tomor ane echar firmware Aar cay O elokans ehan beacon EOCEEN end DII function import function function function function var errmsgBu dataBuff errmsg d neededsi devinfos begin errmsg hf APT if yapi begin write yapilInitAPI mode integer errmsg pansichar integer cdecl external yapi dill name yapialInitAPI yapiUpdateDeviceList force integer errmsg pansichar integer cdecl external yapi dll name yapiUpdateDeviceList yapiGetAllDevices buffer pointer marsoire Integer var neededsize amteger errmsg ipansi chank integer edecls external yapi diMi name yapirGetAlNDevicest apiGetDeviceInfo d integer var infos yDeviceSt errmsg pansuchar ianteqes sedeci external yapi dill name yapiGetDevicelInfo Prerak array Oo o2ekei Cie ans tehar er array oiler tehie aluslicteveisie max of 128 USB devices ata pa
74. 456 MyFunction YVoltage voltage yFindVoltage MyModule voltagel YVoltage voltage yFindVoltage MyModule MyFunction YVoltage voltage yFindVoltage MyFunction yFindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by yFindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get _currentValue method of the object returned by yFindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts 12 2 Control of the module part 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 import lt Foundation Foundation h gt import yocto_api h static void usage const char exe NSLog usage s lt serial or logical name gt ON OFF n exe exit 1 int maan ink arger const cher angi ih NSError error autoreleasepool Setup the API to use local USB devices TE VAP eRe gwsitdersHub Gus Oe error e ArT SUCCESS mat NSLog RegisterHub error error localizedDescription return 1 Tiverge 2 usage argv 0 NSString serial or name NSString stringWithUTF8String argv 1 YModule module Y
75. 5 30 Correction example with 3 calibration points Back to normal To cancel the effect of a calibration on a function call the calibrateFromPoints method with two empty arrays Double ValuesBefore he Double ValuesAfter ee MVCleagew re mMVCll cage gress Violtage s 114 www yoctopuce com 19 Advanced programming f calibrateFromPoints ValuesBefore ValuesAfter f get_module saveToFlash You will find in the Examples Prog Calibration directory of the Delphi VB and C libraries an application allowing you to test the effects of the 1 to 5 point calibration Arbitrary interpolation It is also possible to compute the interpolation instead of letting the module do it in order to calculate a spline interpolation for instance To do so you only need to store a callback in the API This callback must specify the number of calibration points it is expecting public static double CustomInterpolation3Points double rawValue int calibType int parameters double beforeValues double afterValues double result the value to be corrected is rawValue calibration points are in beforeValues and afterValues result interpolation of your choice return result YAPI RegisterCalibrationHandler 3 CustomInterpolation3Points Note that these interpolation callbacks are global and not specific to each function Thus each time someone requests a value from a module which contains in its flas
76. AC null YModule m null if args Length lt 1 usage target args 0 ToUpper Setup the API to use local USB devices if YAPI RegisterHub usb ref errmsg YAPI SUCCESS Console WriteLine RegisterHub error errmsg Environment Exit 0 if target ANY retreive any voltage sensor can be AC or DC sensor YVoltage FirstVoltage if sensor null die No module connected else sensor YVoltage FindVoltage target voltagel we need to retreive both DC and AC voltage from the device if sensor isOnline m sensor get_module sensorDC YVoltage FindVoltage m get_serialNumber voltagel sensorAG VVolitage YindVoltage m geu seriralNumbexr p volltage2 else die Module not connected www yoctopuce com 71 14 Using Yocto Volt with C while true if m isOnline die Module not connected Console Weite APE ses cnsOmDe get eurrentValue ine C sits 110 Ci m sivinel ey Console Write VAC ees cnsoLAG ger eurcentVal uek losers cy O E Mv ly Console WriteLine press Ctrl C to exit YAPI Sleep 1000 ref errmsg 14 4 Control of the module part 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 using System using oys tem eo ections concer ne using System Linq us
77. Age GemGumremtaValte l ume ar Let s look at these lines in more details yocto_api h et yocto_voltage h These two include files provide access to the functions allowing you to manage Yoctopuce modules yocto api h must always be used yocto voltage h is necessary to manage modules containing a voltage sensor such as Yocto Volt yRegisterHub The yRegisterHub 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 yFindVoltage The yFindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once YVoltage voltage YVoltage voltage YVoltage voltage YVoltage voltage YVoltage voltage yFindVoltage VOLTAGE1 123456 voltagel yFindVoltage VOLTAGE1 123456 MyFunction yFindVoltage MyModule voltagel yFi
78. C cerni usager Uli lt lt encu lt Us cial lt newhogucalName gt ls lt lt ends exi ctii ink maiman araqe conet ehari argv SEEGI errmsg Setup the API to use local USB devices i yRegisterHub usb errmsg YAPT SUCCESS Cerin REG SES HUONE rror lt lt omens o comely aeaa Le me enee 2 usage argv 0 YModule module yFindModule argv 1 use serial or logical name if module gt isOnline if arge gt 3 string newname argv 2 if yCheckLogicalName newname cerr lt lt Invalid name lt lt newname lt lt lt lt endl usage argv 0 module gt set_logicalName newname module gt saveToFlash cout lt lt Current name lt lt module gt get_logicalName lt lt endl else cout lt lt argv 1 lt lt not connected check identification and USB cable lt lt endl return 0 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 Listing the modules Obtaining the list of the connected modules is performed with the yFirstModule
79. Each Yoctopuce module has its own REST interface available in several variants Let us imagine a Yocto Volt with the VOLTAGE1 12345 serial number and the myModule logical name The following URL allows you to know the state of the module http 127 0 0 1 4444 bySerial VOLTAGE1 12345 api module txt You can naturally also use the module logical name rather than its serial number http 127 0 0 1 4444 byName myModule api module txt 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 http 127 0 0 1 4444 bySerial VOLTAGE1 12345 api module luminosity To change the value of a property modify the corresponding attribute Thus to modify the luminosity send the following request http 127 0 0 1 4444 bySerial VOLTAGE1 12345 api module luminosity 100 Driving the module functions through the REST interface The module functions can be manipulated in the same way To know the state of the voltage function build the following URL http 127 0 0 1 4444 bySerial VOLTAGE1 12345 api voltage txt 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 http 127 0 0 1 4444 byS
80. For example to obtain the list of all the connected modules use YModule inventory You can also use the following command to obtain an even more detailed list of the connected modules 28 www yoctopuce com 8 Using the Yocto Volt in command line YModule all describe 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 YModule VOLTAGE1 12346 set_logicalName MonPremierModule YModule VOLTAGE1 12346 get_logicalName Changing the settings of the module 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 revert FromFlash method For example YModule VOLTAGE1 12346 set_logicalName MonPremierModule 1 12346 GE YModule VOLTAGE saveToFlash Note that you can do the same thing in a single command with the s option YModule s VOLTAGE1 12346 set_logicalName MonPremierModule Warning the number of write cycles of the nonvolatile memory of the module is limited When this limit is reached nothing guaranties
81. 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 264 www yoctopuce com 21 High level API Reference datalogger set_autoStart YDataLogger datalogger setAutoStart Changes the default activation state of the data logger on power up function set_autoStart newval function set_autoStart newval function set_autoStart newval int set_autoStart Y_AUTOSTART_enum newval int setAutoStart Y_AUTOSTART_enum newval function set_autoStart newval Integer integer function set_autoStart ByVal newval As Integer As Integer int set_autoStart int newval int set_autoStart int newval def set_autoStart newval YDataLogger target set_autoStart newval Remember to call the saveToF lash method of the module if the modification must be kept P Parameters newval either Y_AUTOSTART_OFF or Y_AUTOSTART_ON according to the default activation state of the data logger on power up Returns YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code www yoctopuce com 265 21 High level API Reference datalogger set_logic
82. IAL FUNCTIONID dataset get_measures Returns all measured values currently available for this DataSet as a list of YMeasure objects dataset get_preview Returns a condensed version of the measures that can retrieved in this YDataSet as a list of YMeasure objects dataset get_progress Returns the progress of the downloads of the measures from the data logger on a scale from 0 to 100 dataset get_startTimeUTC Returns the start time of the dataset relative to the Jan 1 1970 dataset get_summary Returns an YMeasure object which summarizes the whole DataSet dataset get_unit Returns the measuring unit for the measured value www yoctopuce com 271 21 High level API Reference dataset loadMore Loads the the next block of measures from the dataLogger and updates the progress indicator dataset loadMore_async callback context Loads the the next block of measures from the dataLogger asynchronously 272 www yoctopuce com 21 High level API Reference dataset get_endTimeUTC YDataSet dataset endTimeUTC Returns the end time of the dataset relative to the Jan 1 1970 function get_endTimeUTC function get_endTimeUTC function get_endTimeUTC s64 get_endTimeUTC s64 endTimeUTC function get_endTimeUTC int64 function get_endTimeUTC As Long long get_endTimeUTC long get_endTimeUTC def get_endTimeUTC When the YDataSet is c
83. ITLE gt lt BODY gt lt FORM method get gt lt php include yocto_api php Use explicit error handling rather than exceptions yDisableExceptions Setup the API to use the VirtualHub on local machine if yRegisterHub http 127 0 0 1 4444 Serrmsg YAPI_SUCCESS 42 www yoctopuce com 10 Using Yocto Volt with PHP dve MGannot contact Vamtualiiib on 27m0 OTIC serra See Serra ae Secreta Yo UN Ff Check if a specified module is available online Smodule yFindModule S serial if Smodule gt isOnline die Module not connected check serial and USB cable else or use any connected module suitable for the demo Smodule yFirstModule if module skip VirtualHub Smodule Smodule gt nextModule if is_null Smodule die No module connected check USB cable else serial module gt get_serialnumber Print Module to use lt input name serial value Sserial gt lt br gt if isset _ GET newname S newname GET newname if yCheckLogicalName S newname die Invalid name module gt set_logicalName newname Smodule gt saveToFlash printf Current name s lt br gt Smodule gt get_logicalName print New name lt input name newname value maxlength 19 gt lt br gt eS lt input type submit gt lt FORM gt lt BODY gt lt HTML gt Warning the number of
84. Module module gt luminosity Returns the luminosity of the module informative leds from 0 to 100 function get_luminosity function get_luminosity function get_luminosity int get_luminosity int luminosity function get_luminosity LongInt function get_luminosity As Integer int get_luminosity int get_luminosity def get_luminosity 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 Y_LUMINOSITY_INVALID www yoctopuce com 167 21 High level API Reference module gt get_persistentSettings YModule module gt persistentSettings Returns the current state of persistent module settings function get_persistentSettings function get_persistentSettings function get_persistentSettings Y_PERSISTENTSETTINGS_ enum get_persistentSettings Y_PERSISTENTSETTINGS_ enum persistentSettings pas _ function get_persistentSettings Integer v _ function get_persistentSettings As Integer int get_persistentSettings int get_persistentSettings def get_persistentSettings YModule target get_persistentSettings Returns a value among Y_PERSISTENTSETTINGS_LOADED Y_PERSISTENTSETTINGS_SAVED and Y_PERSISTENTSETTINGS_MODIFIED corresponding to the current state of persistent module settings On failure throws an exception or return
85. Module FindModule serial or name use serial or logical name if module isOnline a0 large So 4 if stremp argv 2 ON 0 module setBeacon Y BEACON ON else module setBeacon Y BEACON OFF NSLog serial S n module serialNumber NSLog logical name n module logicalName NSLog luminosity Sd n module luminosity NSLog beacon Lee if module beacon Y_BEACON_ON www yoctopuce com 59 12 Using Yocto Volt with Objective C NSLog ON n else NSLog OFF n NSLog upTime d sec n module upTime 1000 NSLog USB current d mA n module usbCurrent NSLog logs n module get_lastLogs else NSLog not connected check identification and USB cable n serial or name 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 Changing the module settings 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 sa
86. TECT_USB Y_DETECT_NET and Y_DET ECT 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 134 www yoctopuce com 21 High level API Reference YAPI PreregisterHub YAPI yPreregisterHub Fault tolerant alternative to RegisterHub function yPreregisterHub url errmsg function PreregisterHub url errmsg function yPreregisterHub url amp errmsg YRETCODE yPreregisterHub const string amp url string amp errmsg YRETCODE yPreregisterHub NSString url NSError errmsg function yPreregisterHub url string var errmsg string integer function yPreregisterHub ByVal url As String ByRef errmsg As String As Integer int PreregisterHub string url ref string errmsg synchronized static int PreregisterHub String url def PreregisterHub url errmsg None This function has the same purpose and same arguments as RegisterHub 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 7 Parameters url a string containing either usb callback or the root URL of the hub to monitor errmsg a string passed by
87. 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 i1sOnline and which could crash the software The only way to prevent this is to implement one of the two error handling techniques described below 74 www yoctopuce com 14 Using Yocto Volt with C 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 e If your code catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang 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 yDisableExceptions 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 eac
88. Vairtkuallub om 127703021 var module function refresh var serial document getElementBylId serial value if serial Detect any conected module suitable for the demo module yFirstModule nextModule if module serial module get seriallNumber document getElementBylId serial value serial module yFindModule serial if module isOnline document getHlementBylId msg value vam htm serra module ge pase ra alNumio er lt br html logical name module get_logicalName lt br gt html luminosity module get_luminosity lt br gt html beacon if module get_beacon Y BEACON ON html 0N lt a href javascript beacon Y BEACON OFF gt switch off lt a gt lt br gt alsa html OFF lt a hrer javascript beacon Y BEACON ON gt switch on lt a gt lt br gt html upTime parseInt modulle get_upTime 1000 sec lt br gt heml USB current tmodule get usbCurrent mA lt br gt html logs lt br gt lt pre gt tmodule get_lastlogs lt pre gt lt br gt document getElementById data innerHTML html else document getHlementById msg value Module not connected setTimeout refresh 1000 function beacon state module set_beacon state refresh gt OCR lt HEAD gt lt BODY onload refresh gt Module to use lt input id serial gt lt input id msg
89. Voltage YVoltage nextVoltage function nextVoltage TYVoltage function nextVoltage As YVoltage YVoltage nextVoltage YVoltage nextVoltage def nextVoltage Returns a pointer to a YVoltage object corresponding to a voltage sensor currently online or a nul pointer if there are no more voltage sensors to enumerate www yoctopuce com 225 21 High level API Reference voltage registerTimedReportCallback YVoltage Registers the callback function that is invoked on every periodic timed notification is__ function registerTimedReportCallback callback node js function registerTimedReportCallback callback php _ function registerTimedReportCallback callback int registerTimedReportCallback YVoltageTimedReportCallback callback int registerTimedReportCallback YVoltageTimedReportCallback callback function registerTimedReportCallback callback TYVoltageTimedReportCallback Longint vo function registerTimedReportCallback As Integer int registerTimedReportCallback TimedReportCallback callback int registerTimedReportCallback TimedReportCallback callback def registerTimedReportCallback 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 ar
90. Y STATE INVALID value a get _currentValue method returns a Y 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 68 www yoctopuce com 14 Using Yocto Volt with C 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 site 14 1 Installation Download the Visual C Yoctopuce library from the Yoctopuce web site There is no setup program simply copy the content of the zip file into the directory of your choice You
91. YAPI RegisterHub usb voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel Hot plug is easy just check that the device is online if voltage isOnline Use voltage get_currentValue lh ee ool Let us look at these lines in more details YAPI EnableUSBHost 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 YAPI RegisterHub 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 YVoltage FindVoltage The YVoltage FindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly eq
92. YVoltage 199 get_autoStart YDataLogger 242 get_averageValue YMeasure 284 get_beacon YModule 158 get_currentRawValue YVoltage 200 get_currentRunIndex YDataLogger 243 get_currentValue YVoltage 201 get_dataSets YDataLogger 244 get_dataStreams YDataLogger 245 get_endTimeUTC YDataSet 272 get_endTimeUTC YMeasure 285 get_errorMessage YDataLogger 246 get_errorMessage YModule 159 get_errorMessage YVoltage 202 get_errorType YDataLogger 247 get_errorType YModule 160 get_errorType YVoltage 203 get_firmwareRelease YModule 161 get_friendlyName YDataLogger 248 get_friendlyName YVoltage 204 get_functionDescriptor YDataLogger 249 get_functionDescriptor YVoltage 205 get_functionld YDataLogger 250 get_functionld YDataSet 273 get_functionld YVoltage 206 get_hardwareld YDataLogger 251 get_hardwareld YDataSet 274 get_hardwareld YModule 162 get_hardwareld YVoltage 207 get_highestValue YVoltage 208 get_icon2d YModule 163 get_lastLogs YModule 164 get_logFrequency YVoltage 209 get_logicalName YDataLogger 252 get_logicalName YModule 165 get_logicalName YVoltage 210 get_lowestValue YVoltage 211 get_luminosity YModule 166 get_maxValue YMeasure 286 get_measures YDataSet 275 get_minValue YMeasure 287 get_module YDataLogger 253 get_module YVoltage 212 get_module_async YDataLogger 254 get_module_async YVoltage 213 get_persistentSettings YModule 167 get_preview YDataSet 276 get_productld YModule 168 get_productNam
93. Yocto Volt User s guide Table of contents Me METRO GUCUIOIN ccsstes cuca taetactrscitnd toca atte dala reat ted anata etree etna Detected 1 TA PREFEQUISITOS sccccctice iessdeceastativbisdeaeedsccpadsceiebasazaidistiadajetecafaibubizesssdcnendscedesusebisaacidie ciufepsascaes 1 132 OptiomalACCESSONISS access iiaae a og a a a Ea a ea ea oes 3 2 PreseMtation sceninio areara a aera Ea aE EEE 5 21 COMMON elements wore A N E 5 22v OPEC eeM E a e aa a aaea A aea EE eaa D eara eE ara 6 3 Electrocution hazards on ccc cece cesses eesees teense eesneeseeseeseesessneenseneeneeneeneeeneenseneeneeneeees 7 3 1 Dangerous COMPONMEMIS rociera areia areca eden eared E coed EEEE ene Ms A a adta EEE 7 4 Direct current vs alternating current oo cece cece cece ee teeeeeeeseeeeneeteeneees 9 oO PINSUSIODS essen ee ee eee hee ehh thei 11 Bil OC AlIZ ATION Saceces ee eee ote sce Ak yeh Atta ai dh caeaake Segue ee ieee E 11 5 2 Testo Ne Module a eeceesvneiet test cope a este bck hadinecs daw aa a Ea S a EE fie tes 11 MELOT OTE LOTA DEA PA A A E venue ciety wertiad eee Meee eee 12 6 Assembly and connections ooo eccec ce cee se ess ees eesee teense eeseeeceneeneenesneseeseeseeneeeeaeeesens 15 Se le od 4 Lo AEE per erence E ferme reece rer rere ry rere ere E rrr tc errr err TE 15 6 2 USB power distribution sessin a a e bene aaea Ae 16 7 Programming general concepts oon cecse cece eeeeseeneeseeeeseeeeeseesceneeneenesnens 17 FA Programming Paradigm aaae
94. _ SUCC ESS 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 48 www yoctopuce com 11 Using Yocto Volt with C 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 site 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 libraries 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
95. _logFrequency newval YVoltage target set_logFrequency newval YVoltage The frequency can be specified as samples per second as sample per minute for instance 15 m or in samples per hour eg 4 h To disable recording for this function use the value OFF r Parameters Returns YAPI_SUCCESS if the call succeeds On failure throws an exception or returns a negative error code newval a string corresponding to the datalogger recording frequency for this function www yoctopuce com 229 21 High level API Reference voltage set_logicalName YVoltage voltage setLogicalName Changes the logical name of the voltage sensor function set_logicalName newval function set_logicalName newval function set_logicalName newval int set_logicalName const string amp newval int setLogicalName NSString newval function set_logicalName newval string integer function set_logicalName ByVal newval As String As Integer int set_logicalName string newval int set_logicalName String newval def set_logicalName newval YVoltage 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 voltage sensor Returns YAPI_SUCCESS if the call succeeds On failur
96. a screw head no larger than 4 5mm The best way is to use threaded spacers which you can then mount wherever you want You can find more details on this topic in the chapter about assembly and connections Micro USB hub If you intend to put several Yoctopuce modules in a very small space you can connect them directly to a micro USB hub Yoctopuce builds a USB hub particularly small for this purpose down to 20mmx36mm on which you can directly solder a USB cable instead of using a USB plug For more details see the micro USB hub information sheet YoctoHub Ethernet and YoctoHub Wireless You can add network connectivity to your Yocto Volt thanks to the YoctoHub Ethernet and the YoctoHub Wireless The YoctoHub Ethernet provides Ethernet connectivity and the YoctoHub Wireless provides WiFi connectivity Both can drive up to three devices and behave exactly like a regular computer running a Virtua Hub Enclosures Your Yocto Volt has been designed to be installed as is in your project Nevertheless Yoctopuce sells enclosures specifically designed for Yoctopuce devices These enclosures have removable mounting brackets and magnets allowing them to stick on ferromagnetic surfaces More details are available on the Yoctopuce web site The suggested enclosure model for your Yocto Volt is the YoctoBox Long Thick Black 4 http www yoctopuce com EN products category enclosures www yoctopuce com 3 1 Introduction You can instal
97. aSetChanged handler postDelayed r 500 Override protected void onStop super onStop handler removeCallbacks r YAPI FreeAPI www yoctopuce com 99 18 Using the Yocto Volt with Android Override public void onItemSelected AdapterView lt gt parent View view int pos long id serial parent getItemAtPosition pos toString Override public void onNothingSelected AdapterView lt gt arg0 final Runnable r new Runnable public void run if serial null YVolitage de sensor YVoltage FindVoltage serial voltagell Loy a TextView view TextView findViewById R id dcfield Views eet Seino r ormat luc cSn miCmSeMS orn Get Cuaron Valine dessensor gecUmistr ye Pe Carch ya WAPI Ge pienso mec e printStackTrace VVOlLagenacmsensons Voltage Fmd Voleacgel sencilla RVO tage try TextView view TextView findViewById R id acfield venvdset Texto tring ormat eek ieS aeien Or mc eis Cueme mle yiaelauen iy ae senser Gerum a eaeh RYA ETREX CEPE TONTE enprintorackiraceiNi handler postDelayed this 1000 18 6 Control of the module part 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 package com yoctopuce doc_ examples import android app Activity import android os Bu
98. achine 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 Virtual hub C Objective C s Delphi Python VisualBasic Net s C Net Javascript Node js PHP Java Java for Android Command line Support methods for different languages Limitations of the Yoctopuce libraries 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 7 7 Programming where to start At this point of the user s guide you should know the main theoretical points of your Yocto Volt It is now time to practice You must download the Yoctopuce library for your favorite programming language from the Yoctopuce web site Then skip directly to the chapter corresponding to the chosen programming language All the examples described in this guide are available in the programming librari
99. age YVoltage FindVoltage VOLTAGE1 123456 MyFunction voltage YVoltage FindVoltage MyModule voltagel voltage YVoltage FindVoltage MyModule MyFunction voltage YVoltage FindVoltage MyFunction YVoltage FindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by YVoltage FindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get_currentValue method of the object returned by YVoltage FindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts A real example Launch you Java environment and open the corresponding sample project provided in the directory Examples Doc GettingStarted Yocto Volt 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 import com yoctopuce YoctoAPI public class Demo public static void main String args try setup the API to use local VirtualHub YAPI RegisterHub 127 0 0 1 cach VAP TO EZ Cep Oner Smo tem ont OE Initlinn Cannot Conka cE Vinea oron 1l2s7 Or Osos met ex getLocalizedMessage System out printin Ensure that the VirtualHub application is running System exit 1 Sreiciwine eienn
100. age sensors with the same logical name are used in the same 20 www yoctopuce com 7 Programming general concepts 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 advertisedValue Short character string summarizing the current state of the voltage sensor that is automatically advertised up to the parent hub For a voltage sensor the advertised value is the measured value unit Short character string representing the measuring unit for the measured value currentValue Current voltage in volts as a floating point number lowestValue Minimal voltage observed as a floating point number highestValue Maximal voltage observed as a floating point number logFrequency Datalogger recording frequency or OFF when measures should not be stored in the data logger flash memory reportFrequency Timed value notification frequency or OFF when timed value notifications are disabled for this function calibrationParam Extra calibration parameters for instance to compensate for the effects of an enclosure as an array of 16 bit words resolution Measure resolution i e precision of the numeric representation not necessarily of the measure itself 7 5 DataLogger function interface Yoctopuce sensors include a non volatile memory capable of storing ongoing measured data automatically wit
101. ageValue Returns the average value observed during the time interval covered by this measure function get_averageValue function get_averageValue function get_averageValue double get_averageValue double averageValue function get_averageValue double function get_averageValue As Double double get_averageValue double get_averageValue def get_averageValue Returns a floating point number corresponding to the average value observed www yoctopuce com 285 21 High level API Reference measure gt get_endTimeUTC YMeasure measure endTimeUTC Returns the end time of the measure relative to the Jan 1 1970 UTC Unix timestamp function get_endTimeUTC function get_endTimeUTC function get_endTimeUTC double get_endTimeUTC double endTimeUTC function get_endTimeUTC double function get_endTimeUTC As Double double get_endTimeUTC double get_endTimeUTC def get_endTimeUTC When the recording rate is higher then 1 sample per second the timestamp may have a fractional part Returns an floating point number corresponding to the number of seconds between the Jan 1 1970 UTC and the end of this measure 286 www yoctopuce com 21 High level API Reference measure get_maxValue YMeasure measure maxValue Returns the largest value observed during the time interval covered by this measure function get_maxValue functi
102. alName YDataLogger datalogger setLogicalName Changes the logical name of the data logger function set_logicalName newval function set_logicalName newval function set_logicalName newval int set_logicalName const string amp newval int setLogicalName NSString newval function set_logicalName newval string integer function set_logicalName ByVal newval As String As Integer int set_logicalName string newval int set_logicalName String newval def set_logicalName newval YDataLogger 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 data logger Returns YAPI_SUCCESS if the call succeeds On failure throws an exception or returns a negative error code 266 www yoctopuce com 21 High level API Reference datalogger set_recording datalogger setRecording Changes the activation state of the data logger to start stop recording data function set_recording newval function set_recording newval function set_recording newval int set_recording Y_RECORDING_enum newval int setRecording Y_RECORDING_enum newval function set_recording newval Integer integer function set_recording ByVal newval As Integer As Integer int set_recording in
103. allback function to be called each time a device is unpluged function yRegisterDeviceRemovalCallback removalCallback function RegisterDeviceRemovalCallback removalCallback function yRegisterDeviceRemovalCallback removalCallback void yRegisterDeviceRemovalCallback yDeviceUpdateCallback removalCallback void yRegisterDeviceRemovalCallback yDeviceUpdateCallback removalCallback procedure yRegisterDeviceRemovalCallback removalCallback yDeviceUpdateFunc procedure yRegisterDeviceRemovalCallback ByVal removalCallback As yDeviceUpdateFunc void RegisterDeviceRemovalCallback yDeviceUpdateFunc removalCallback synchronized static void RegisterDeviceRemovalCallback DeviceRemovalCallback removalCallback def 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 www yoctopuce com 137 21 High level API Reference YAPI RegisterHub YAPI yRegisterHub Setup the Yoctopuce library to use modules connected on a given machine function yRegisterHub url errmsg node js function RegisterHub url errmsg php function yRegisterHub url amp errmsg YRETCODE yRegisterHub const string amp url string amp errmsg YRETCODE yRegisterHub NSString url NSError errmsg function yRegisterHub url string var errmsg st
104. amming 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 Low level handling Module handling Feature handling YAPI YModule YTemperature YPressure YRelay Y XXX Structure of the Yoctopuce API 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 www yoctopuce com 17 7 Programming general concepts From the programming stand point your Yocto Volt is viewed as a module hosting a given number of functions In the API these functions are objects which can be found independently in several ways Access to the functions of a module Access by logical
105. an use as a basis Example 1 51 yoctopuce rules 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 Example 2 51 yoctopuce_group rules 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 1 http www yoctopuce com FR virtualhub php www yoctopuce com 291 22 Troubleshooting 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 22 2 ARM Platforms HF and EL 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 dif
106. ather than exceptions yDisableExceptions Setup the API to use the VirtualHub on local machine if yRegisterHub http 127 0 0 1 4444 Serrmsg YAPI SUCCESS die Cannot contact VirtualHub on 127 0 0 1 Serrmsg www yoctopuce com 41 10 Using Yocto Volt with PHP Sserial GET serial ie Geertie P 0 Check if a specified module is available online Smodule yFindModule S serial if Smodule gt isOnline die Module not connected check serial and USB cable else or use any connected module suitable for the demo Smodule yFirstModule if module skip VirtualHub Smodule Smodule gt nextModule if is_null Smodule die No module connected check USB cable else serial module gt get_serialnumber Print Module to use lt input name serial value Sserial gt lt br gt ii Grsisct GmGhllmbeaconm i ia if _GET beacon ON module gt set_beacon Y BEACON ON else S module gt set_beacon Y BEACON OFF printf serial s lt br gt module gt get_serialNumber printf logical name s lt br gt module gt get_logicalName printf luminosity s lt br gt module gt get_luminosity Primi oeacons uE if Smodule gt get_beacon Y BEACON ON printf lt input type radio name beacon value ON checked gt ON printf lt input type radio name beacon value OFF gt OFF l
107. ating all the sources of the library into your projects has several advantages e It guaranties the respect of the compilation conventions of your project 32 64 bits inclusion of debugging symbols unicode or ASCII characters etc 54 www yoctopuce com 11 Using Yocto Volt with C e It facilitates debugging if you are looking for the cause of a problem linked to the Yoctopuce library e It reduces the dependencies on third party components for example in the case where you would need to recompile this project for another architecture in many years e It does not require the installation of a dynamic library specific to Yoctopuce on the final system everything is in the executable 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 For Windows the libraries are added automatically e For Mac OS X IOKit framework and CoreFoundation framework e For Linux libm libpthread libusb1 0 and libstdc Integration as a static library Integration of the Yoctopuce library as a static library is a simpler manner to build a small executable which uses Yoctopuce modules You can quickly compile the program with a single command You do
108. b const string amp url void yUnregisterHub NSString url procedure yUnregisterHub url string procedure yUnregisterHub ByVal url As String void UnregisterHub string url synchronized static void UnregisterHub String url def UnregisterHub url Parameters url a string containing either usb or the www yoctopuce com 145 21 High level API Reference YAPI UpdateDeviceList YAPI yUpdateDeviceList Triggers a re detection of connected Yoctopuce modules function yUpdateDeviceList errmsg node js function UpdateDeviceList errmsg function yUpdateDeviceList amp errmsg YRETCODE yUpdateDeviceList string amp errmsg YRETCODE yUpdateDeviceList NSError errmsg function yUpdateDeviceList var errmsg string integer function yUpdateDeviceList ByRef errmsg As String As YRETCODE YRETCODE UpdateDeviceList ref string errmsg int UpdateDeviceList def UpdateDeviceList errmsg None 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 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
109. bjective C libraries 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 example with video shots showing how to integrate the library into your projects 12 1 Control of the Voltage function Launch Xcode 4 2 and open the corresponding sample project provided in the directory Examples Doc GettingStarted Yocto Volt of the Yoctopuce library import lt Foundation Foundation h gt import yocto_api h import yocto_voltage h static void usage void NSLog usage demo lt serial number NSLog demo lt logical_ name gt NSLog demo any usevanyaduscovered idevaice il exit dhi int mann Ime drogei const char aarov 1 1 www yoctopuce com EN libraries php 2 www yoctopuce com EN article new objective c library for mac os x www yoctopuce
110. ble the measure is Above 80Hz the higher the frequency is the more underestimated the measure is Note that the AC measure given by the Yocto Volt does not correspond to the voltage peak amplitude but to the RMS value 10 www yoctopuce com 5 First steps When reading this chapter your Yocto Volt 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 software 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 browser 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 Serial Logical Name Description Action idlas fk VirtualHub Configure view log file 026C8 Yocto Volt configure view log file beacon fe r Show device functions Module list as displayed in your web bowser 5 1 Localization You can then physically localize each of the displayed modules by clicking on the beacon button This puts the Yocto led of the corresponding module in Yocto beacon mode It starts
111. cal Name Description Action VIRTHUB0 7d1a86fb0 VirtualHub configure view log file RELAYHI 55 Yocto PowerRelay Configure view log fie beacon TMPSENS1 0S5E7F Yocto Temperature configure view log file beacon l Show device functions Click on the configure button on the first line www yoctopuce com 45 10 Using Yocto Volt with PHP VIRTHUBO 7d1a86fb09 Edit parameters for VIRTHUBO 7d1a86f009 and click on the Save button Serial VIRTHUB0 7d1a86fb09 Product name VirtualHub Software version 10789 Logical name Incoming connections Authentication to read information from the devices NO edit Authentication to make changes to the devices NO gait Outgoing callbacks Callback URL octoHub Gi Delay between callbacks min 3 s max 600 s This VirtualHub can post the advertised values of all devices on a specific URL on a regular basis If you wish to use this feature choose the callback type follow the steps below carefully 1 Specify the Type of callback you want to use Yocto API callback z Yoctopuce devices can be controled through remote PHP scripts That Yocto AFP caliback protocol is designed so it can pass trough NAT filters without opening ports See your device user manual PHP programming section for more details 2 Specify the URL to use for reporting values HTTPS protocol is not yet supported Callback URL http iwww mysite com yoctotest yoctocontrol php
112. ceList function yapiHTTPRequest device pansichar url pansichar buffer pansichar butisaze integer var EUSE neeger errmsg 3 pansichar integer caeci external yapi dll name yapiHTTPRequest var errmsgBuffer array 0 256 of ansichar dataBuffer array LO TTo 4 Mot anisae alc errmsg data pansitehar TE BUL Salva e ANEEL const serial VOLTAGE1 12345 getValue GET api module luminosity HTTP 1 1 13 10 13 10 setValue GET api module luminosity 100 HTTP 1 1 13 10 13 10 begin errmsg G errmsgBuffer data dataBuffer API initialization if yapiInitAPI 1 errmsg lt 0 then begin writeln errmsg Dalit endi forces a device inventory if yapiUpdateDeviceList 1 errmsg lt 0 then begin writeln errmsg heey end requests the module luminosity if yapiHTTPRequest serial getValue data sizeof dataBuffer fullsize errmsg lt 0 then begin writeln errmsg halt end searches for the HTTP header end p pos 13410 13 10 data displays the response minus the HTTP header writeln copy data p 4 length data p 3 changes the luminosity if yapiHTTPRequest serial setValue data sizeof dataBuffer fullsize errmsg lt 0 then begin writeln errmsg halt end end Module inventory To perform an inventory of Yoctopuce modules you need two functions from the dynamic library int yapiGetAllDevices int buffer int maxsize int neededsize char
113. ceeds On failure throws an exception or returns a negative error code 222 www yoctopuce com 21 High level API Reference voltage loadCalibrationPoints YVoltage Retrieves error correction data points previously entered using the method calibrateFromPoints function loadCalibrationPoints rawValues refValues function loadCalibrationPoints rawValues refValues function loadCalibrationPoints amp rawValues amp refValues int loadCalibrationPoints vector lt double gt amp rawValues vector lt double gt amp refValues int loadCalibrationPoints NSMutableArray rawValues NSMutableArray refValues function loadCalibrationPoints var rawValues TDoubleArray var refValues TDoubleArray LongInt procedure loadCalibrationPoints int loadCalibrationPoints List lt double gt rawValues List lt double gt refValues int loadCalibrationPoints ArrayList lt Double gt rawValues ArrayList lt Double gt refValues def loadCalibrationPoints rawValues refValues YVoltage target loadCalibrationPoints rawValues refValues Parameters rawValues array of floating point numbers that will be filled by the function with the raw sensor values for the correction points refValues array of floating point numbers that will be filled by the function with the desired values for the correction points Returns YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code
114. code or YAPT_SUCCESS context caller specific object that is passed as is to the callback function Returns nothing the result is provided to the callback www yoctopuce com 181 21 High level API Reference module nextModule YModule Continues the module enumeration started using yFirstModule is _ function nextModule node js function nextModule php_ function nextModule cpp _ YModule nextModule YModule nextModule function nextModule TYModule vb _ function nextModule As YModule YModule nextModule YModule nextModule def nextModule Returns a pointer to a YModu1e object corresponding to the next module found or a nu11 pointer if there are no more modules to enumerate 182 www yoctopuce com 21 High level API Reference module reboot Schedules a simple module reboot after the given number of seconds function reboot secBeforeReboot function reboot secBeforeReboot function reboot secBeforeReboot int reboot int secBeforeReboot int reboot int secBeforeReboot function reboot secBeforeReboot Longint Longint function reboot As Integer int reboot int secBeforeReboot int reboot int secBeforeReboot def reboot secBeforeReboot YModule target reboot secBeforeReboot YModule Parameters secBeforeReboot number of seconds before rebooting Returns YAPI_SUCCESS when the call s
115. cro 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 Listing the modules 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 package com yoctopuce doc_ examples import android app Activity import android os Bundle import android view View import android widget LinearLayout import android widget TextView import com yoctopuce YoctoAPI YAPI import com yoctopuce YoctoAPI YAPI Exception import com yoctopuce YoctoAPI YModule public class Inventory extends Activity Override public void onCreate Bundle savedInstanceState super onCreate savedIinstanceState setContentView R layout inventory public void refreshInventory View view LinearLayout layout LinearLayout findViewById R id inventoryList layout removeAllViews Cry 4 YAPI UpdateDeviceList YModule module YModule FirstModule while module null String line module get_serialNumber module get_productName TextView tx new TextView this tx setText line
116. ction get_logicalName string get_logicalName NSString logicalName function get_logicalName string function get_logicalName As String string get_logicalName String get_logicalName def get_logicalName YVoltage target get_logicalName Returns a string corresponding to the logical name of the voltage sensor On failure throws an exception or returns Y_LOGICALNAME_INVALID www yoctopuce com 211 21 High level API Reference voltage get_lowestValue voltage lowestValue Returns the minimal value observed function get_lowestValue function get_lowestValue function get_lowestValue double get_lowestValue double lowestValue function get_lowestValue function get_lowestValue double get_lowestValue double get_lowestValue def get_lowestValue YVoltage target get_lowestValue double As Double Se Returns a floating point number corresponding to the minimal value observed On failure throws an exception or returns Y_LOWESTVALUE_INVALID YVoltage 212 www yoctopuce com 21 High level API Reference voltage get_module voltage module Gets the YModule object for the device on which the function is located function get_module function get_module function get_module YModule get_module YModule module function get_module TYModule function get_module As YModule YModule get_module YModule get_modu
117. ction yEnableExceptions node js function EnableExceptions function yEnableExceptions void yEnableExceptions void yEnableExceptions procedure yEnableExceptions procedure yEnableExceptions cs void EnableExceptions def 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 128 www yoctopuce com 21 High level API Reference YAPI EnableUSBHost YAPI yEnableUSBHost This function is used only on Android synchronized static 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 subclasee 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 www yoctopuce com 129 21 High level API Reference YAPI FreeAPI YAPI yFreeAPI Frees dynamically allocated memory blocks used by the Yoctopuce library is _ function yFreeAPI node js function FreeAPI php _ function yFreeAPI void yFreeAPI void yFreeAPI procedure yFreeAPI procedure yFreeAPI void FreeAPI
118. d in order to be handled This is generally not guaranteed as a USB module can be disconnected after the control software has started The isOnline method available in all the classes is then very helpful Access to the modules Even if it is perfectly possible to build a complete project while making a total abstraction of which function is hosted on which module the modules themselves are also accessible from the API In fact they can be handled in a way quite similar to the functions They are assigned a serial number at the factory which allows you to find the corresponding object with YModule Find You can also assign arbitrary logical names to the modules to make finding them easier Finally the YModule class contains the YModule FirstModule and nextModule enumeration methods allowing you to list the connected modules Functions Module interaction From the API standpoint the modules and their functions are strongly uncorrelated by design Nevertheless the API provides the possibility to go from one to the other Thus the get_module method available for each function class allows you to find the object corresponding to the module hosting this function Inversely the YModule class provides several methods allowing you to enumerate the functions available on a module 7 2 The Yocto Volt module The Yocto Volt module provides a two instances of the Voltage function The voltagel input corresponds to the DC voltage component
119. define your callback as a global procedure which then calls your method If you need to keep a reference to your object you can store it directly in the YVoltage object using function set _userData You can then retrieve it in the global callback procedure using get_userData Setting up a value change callback The callback is set up for a given Voltage function with the help of the registerValueCallback method The following example sets up a callback for the first available Voltage function YVoltage f YVoltage FirstVoltage f registerValueCallback voltagelChangeCallBack Note that each module function can thus have its own distinct callback By the way if you like to work with value change callbacks you will appreciate the fact that value change callbacks are not limited to sensors but are also available for all Yoctopuce devices for instance you can also receive a callback any time a relay state changes The timed report callback This type of callback is automatically called at a predefined time interval The callback frequency can be configured individually for each sensor with frequencies going from hundred calls per seconds down to one call per hour The callback takes as parameter the relevant function and the measured value as an YMeasure object Contrarily to the value change callback that only receives the latest value an YMeasure object provides both minimal maximal and average values since the timed report callback
120. 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 e If your code catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang As this latest situation is not the most desirable the Yoctopuce library of
121. ds On failure throws an exception or returns a negative error code www yoctopuce com 233 21 High level API Reference voltage set_userData YVoltage voltage setUserData Stores a user context provided as argument in the userData attribute of the function function set_userData data function set_userData data function set_userData data void set_userData void data void setUserData void data procedure set_userData data Tobject procedure set_userData ByVal data As Object void set_userData object data void set_userData Object data def 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 234 www yoctopuce com 21 High level API Reference voltage wait_async YVoltage Waits for all pending asynchronous commands on the module to complete and invoke the user provided callback function function wait_async callback context function 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 speci
122. dvevevavenueencesh 74 15 Using Yocto Volt with Delphi oo cece cece cece eeneeeeneeseeteseeeesneeeenees 77 15 1 PROPAratiOn e a a aaa a T T Aa Ra Eaa Eaa DEA ia an iaaea E Aaaa Aieiaia at 77 15 2 Control of the Voltage function oe cece eeeneeeeeeneeeeeeaaeeeeteaeeeeteaeeeeteaeeeeeeaeeeeseeaeesenaaeeey 77 15 3 Controlot the module part 2 aan aidan nis a ne a a 79 154s ErrOrnangling xis cise dente dea senile dad anion i a iE Gate eels 81 16 Using the Yocto Volt with Python 20 cece cece ceeeeeeeseeseeteseaneeneees 83 VST SOUPCO MISS EA EPE ee savedeuck aided Neasehe Pe sin Gach cass T 83 16 2 Dynamic brayna a citar eerere ee rer erer ere preerrep ere a ren er rea ererer rer reecrrer ene 83 16 3 Control of the Voltage function occ ceeenee erent ee eee nee eeteaeeeeteaeeeeteaeeeeseaeeeeseaeaeeseaaeeey 83 16 4 Control ot the module Part cia tadeescied eles e aa a aer ieee el eee 85 16 55 Error MANGIING i aT e T a aaa e Aa aa aA a aada aa ae ea TAAA a Sa aiddir 87 17 Using the Yocto Volt With Java oo ccccceccccccceeeseeseeseeseeseeeeeeseeseeneeneaneeees 89 TNA GOMING TOAD A E AE E E E A A vere teheteeateiteetiads 89 17 2 Control of the Voltage function ssessesessieesrisesrrsssrnssrnrnstrrnnrrnnntrantstnnnnttantnennsttnantnennnena 89 17 3 Control of the MOdUle part sheir eee eee ceeeesseeeeeseeeeeeceeceeeesaeeceesanseseeaeesesaaeeseseaneneenneneennees 91 174 Error handling ink acted see Ree i eno ada RARE ae RES 93 18 Using the
123. e double highestValue function get_highestValue double function get_highestValue As Double double get_highestValue double get_highestValue def get_highestValue YVoltage target get_highestValue Returns a floating point number corresponding to the maximal value observed On failure throws an exception or returns Y_HIGHESTVALUE_INVALID YVoltage www yoctopuce com 209 21 High level API Reference voltage get_logFrequency YVoltage voltage logFrequency Returns the datalogger recording frequency for this function or OFF when measures are not stored in the data logger flash memory function get_logFrequency function get_logFrequency function get_logFrequency string get_logFrequency NSString logFrequency function get_logFrequency string function get_logFrequency As String string get_logFrequency String get_logFrequency def get_logFrequency YVoltage target get_logFrequency Returns a string corresponding to the datalogger recording frequency for this function or OFF when measures are not stored in the data logger flash memory On failure throws an exception or returns Y_LOGFREQUENCY_INVALID 210 www yoctopuce com 21 High level API Reference voltage get_logicalName YVoltage voltage logicalName Returns the logical name of the voltage sensor function get_logicalName function get_logicalName fun
124. e 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 8 2 Use general description All the command line API executables work on the same principle They must be called the following way Executable options target command parameter 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 lif you want to recompile the command line API you also need the C API 2 http www yoctopuce com EN libraries php www yoctopuce com 27 8 Using the Yocto Volt in command line 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 executable help to know the list of available commands for a given command line API ex
125. e AUSB current M Str m get UsbEUrcrent ODE AETA Console WriteLine Logs Console WriteLine Else Console WriteLine argv 1 not connected check identification and USB cable End If m get_lasthogs End Sub End Module 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 Changing the module settings 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 66 www yoctopuce com 13 Using Yocto Volt with Visual Basic NET Module Modulel Sub usage Console WriteLine usage demo lt serial or logical name gt lt new logical name gt End End Sub Sub Main Dim argv As String System Environment GetCommandLineArgs Dim errmsg As String Dim
126. e YModule 169 get_productRelease YModule 170 get_progress YDataSet 277 get_rebootCountdown YModule 171 get_recordedData YVoltage 214 get_recording YDataLogger 255 get_reportFrequency YVoltage 215 get_resolution YVoltage 216 get_serialNumber YModule 172 get_startTimeUTC YDataSet 278 get_startTimeUTC YMeasure 288 get_summary YDataSet 279 get_timeUTC YDataLogger 256 get_unit YDataSet 280 get_unit YVoltage 217 get_upTime YModule 173 get_usbBandwidth YModule 174 get_usbCurrent YModule 175 get_userData YDataLogger 257 get_userData YModule 176 get_userData YVoltage 218 GetAPIVersion YAPI 130 GetTickCount YAPI 131 H HandleEvents YAPI 132 Hazards 7 High level 123 HTTP 44 117 InitAP YAPI 133 Installation 63 69 Installing 27 Integration 54 Interface 148 193 236 Introduction 1 isOnline YDataLogger 258 isOnline YModule 177 isOnline YVoltage 219 isOnline_async YDataLogger 259 isOnline_async YModule 178 isOnline_async YVoltage 220 J Java 89 Javascript 31 L Languages 117 Libraries 119 Library 54 83 122 Limitations 29 Linux 291 load YDataLogger 260 load YModule 179 load YVoltage 221 load_async YDataLogger 261 load_async YModule 180 load_async YVoltage 223 loadCalibrationPoints YVoltage 222 loadMore YDataSet 281 loadMore_async YDataSet 282 Localization 11 Logger 110 Measured 284 Module 11 18 19 28 33 41 51 59 66 72 79 85 91 100 148 N
127. e the returned instance of YModu1e is not shown as on line Returns an instance of YModule 254 www yoctopuce com 21 High level API Reference datalogger get_module_async YDataLogger datalogger module_async Gets the YModul1e object for the device on which the function is located asynchronous version function get_module_async callback context 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 Javascript 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 www yoctopuce com 255 21 High level API Reference datalogger get_recording YDataLogger datalogger recording Returns the current activation state of the data logger function get_recording function get_recording functi
128. e throws an exception or returns a negative error code 230 www yoctopuce com 21 High level API Reference voltage set_lowestValue voltage setLowestValue Changes the recorded minimal value observed function set_lowestValue newval function set_lowestValue newval function set_lowestValue newval int set_lowestValue double newval int setLowestValue double newval function set_lowestValue newval double integer function set_lowestValue ByVal newval As Double As Integer int set_lowestValue double newval int set_lowestValue double newval def set_lowestValue newval YVoltage target set_lowestValue newval Parameters newval a floating point number corresponding to the recorded minimal value observed Returns YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code YVoltage www yoctopuce com 231 21 High level API Reference voltage set_reportFrequency YVoltage voltage setReportFrequency Changes the timed value notification frequency for this function function set_reportFrequency newval function set_reportFrequency newval function set_reportFrequency newval int set_reportFrequency const string amp newval int setReportFrequency NSString newval function set_reportFrequency newval string integer function set_reportFrequency ByVal newval As String As Integer int set_reportFreque
129. e without ending limit Returns an instance of YDataSet providing access to historical data Past measures can be loaded progressively using methods from the YDataSet object www yoctopuce com 215 21 High level API Reference voltage get_reportFrequency YVoltage voltage reportFrequency Returns the timed value notification frequency or OFF if timed value notifications are disabled for this function function get_reportFrequency function get_reportFrequency function get_reportFrequency string get_reportFrequency NSString reportFrequency function get_reportFrequency string function get_reportFrequency As String string get_reportFrequency String get_reportFrequency def get_reportFrequency YVoltage target get_reportFrequency Returns a string corresponding to the timed value notification frequency or OFF if timed value notifications are disabled for this function On failure throws an exception or returns Y_REPORTFREQUENCY_INVALID 216 www yoctopuce com 21 High level API Reference voltage get_resolution YVoltage voltage resolution Returns the resolution of the measured values function get_resolution function get_resolution function get_resolution double get_resolution double resolution function get_resolution double function get_resolution As Double double get_resolution double get_resolution de
130. e 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 16 3 Control of the Voltage function A few lines of code are enough to use a Yocto Volt Here is the skeleton of a Python code snipplet to use the Voltage function 1 http www python org download www yoctopuce com EN libraries php www yoctopuce com 83 16 Using the Yocto Volt with Python erences errmsg YRef Param Get access to your device connected locally on USB for instance YAPI RegisterHub usb errmsg voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel Hot plug is easy just check that the device is online if voltage isOnline Use voltage get_currentValue EAN Let s look at these lines in more details YAPI RegisterHub 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
131. e catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang 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 yDisableExceptions 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 Y STATE INVALID value a get _currentValue method returns a Y 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 www yoctopuce com 47 10 Using Yocto Volt with PHP bounds for the returned value In the case of functions which do not normally return information the return value is YAPI
132. e 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 260 www yoctopuce com 21 High level API Reference datalogger load YDataLogger Preloads the data logger cache with a specified validity duration function load msValidity function load msValidity function load msValidity YRETCODE load int msValidity YRETCODE load int msValidity function load msValidity integer YRETCODE function load ByVal msValidity As Integer As YRETCODE YRETCODE load int msValidity int load long msValidity def 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 trafic for instance Parameters msValidity an integer corresponding to the validity attributed to the loaded function param
133. e 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 REST interface 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 Virtua Hub 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 Virtua Hub is running you obtain the list of the connected modules http 127 0 0 1 4444 api services whitePages txt www yoctopuce com 117 20 Using with unsupported languages 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 Driving a module through the REST interface
134. e the application will run yocto dll for Windows libyocto so 1 0 1 for Mac OS X and Linux 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 Then for you project to build correctly you need to link with your project the dynamic Yoctopuce library and the prerequisite system libraries e For Windows yocto lib e For Mac OS X libyocto lOKit framework and CoreFoundation framework e For Linux libyocto libm libpthread libusb1 0 and libstdc With GCC the command line to compile is simply www yoctopuce com 55 11 Using Yocto Volt with C cise e546 Silverio Slim Siloiwniaseicl Sikuisio il 510 llisictelerrer 56 www yoctopuce com 12 Using Yocto Volt with Objective C 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 O
135. e voltage sensor isOnline The isOnline method of the object returned by yFindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get _currentValue method of the object returned by yFindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts A real example Open your preferred text editor 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 Volt 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 4 if you do not have a text editor use Notepad rather than Microsoft Word 40 www yoctopuce com 10 Using Yocto Volt with PHP lt HTML gt lt HEAD gt lt TITLE gt Hello World lt TITLE gt lt HEAD gt lt BODY gt lt php include yocto_api php include yocto_voltage php Use explicit error handling rather than exceptions yDisableExceptions Setup the API to use the VirtualHub on local machine if yRegisterHub http 127 0 0 1 4444 Serrmsg YAPT SUCCESS die Cannor contact Vixrtuallhub on 227 005 1M Sser
136. eai aaaea aande ae Aa ae ada A Aaaa aaea a aa oe a es ae eo 17 7 2 Whe Yocto Volt Mod le icsc08 20s caeer ever ieden foc eeeeedi ener e aaa ad ee aair EEE darada Eua ed 18 7 3 Module control interface oo ceeceeceesseceeeeeeeeeenseneeeenaneeeeaneceeaneceesaneeneaaeensnsneenessinenensanes 19 7 4 Voltage function interface o oo eeseeeecesneeeeseneeeeneneceenaneeneaaeenessanenecsaneeeeseneesensneeeenenseneaas 20 7 5 DataLogger function interface oo ee ceeeseceeeseeceeeeeeceeeeeeeeceeeeeeeneseaeeseeaaeenensanenessneeeesneeeesas 21 7 6 What interface Native DLL or Service oi cceccccccsceeceeeeeseeeeeceueeeeeeeesueeeeseseeeeeeeeeeenaes 22 1 0 Programming Where tO Start ari iee eaaa eiaa ieee eet eh iene tee 24 8 Using the Yocto Volt in Command line on eee eeteeee testes teeeeeetee 27 sel eal Lats t ll late Reerrerereeeecmerer epee rere ttre rere rere tere come rrrrcon reer eree coreerereT eererr tree a rer er errr 27 8 27 Use eneral GSSCriptlom saa a raa deaa e coset cca g aces vacded dpe setwecdstecesduceaedatvaced iaioa ieia zea 27 8 3 Control of the Voltage FUNCTION ooo ee ceeeeeee eee eeeeeeeeeeeeeeeeeeeeeaeeeeesaaeeesecaeeeesneeeetseeeeenaes 28 8 4 Control of the Module Part ooo eee seeeseseeeeceeneeeeeneeeeeeeeeeenansenenaaeeneaaeeseenaneeeenaneeeesneenenaes 28 8 5 LIMMAUOMS 2 2 14 atic EE E E cece aati tee tee 29 9 Using Yocto Volt with Javascript oo ccc ccc cece ee eee eeeeseeeteseeseeneeneeeeseeneens 31 9
137. ecutable or even executable command help to obtain a detailed description of the parameters of a command 8 3 Control of the Voltage function To control the Voltage function of your Yocto Volt you need the YVoltage executable file For instance you can launch YVoltage any get _currentValue This example uses the any target to indicate that we want to work on the first Voltage 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 Volt module with the VOLTAGE1 123456 serial number which you have called MyModule and its voltage1 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 YVoltage VOLTAGE1 123456 voltagel describe YVoltage VOLTAGE1 123456 MyFunction describe YVoltage MyModule voltagel describe YVoltage MyModule MyFunction describe YVoltage MyFunction describe To work on all the Voltage functions at the same time use the all target YVoltage all describe For more details on the possibilities of the YVoltage executable use YVoltage help 8 4 Control of the module part Each module can be controlled in a similar way with the help of the YModule executable
138. ed the API calls a callback function which you have defined in advance Detecting module arrival and departure 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 The callback is the function which is called each time a new Yoctopuce module is connected It takes as parameter the relevant module static void deviceArrival YModule m Console WriteLine New module m get_serialNumber www yoctopuce com 107 19 Advanced programming Initialization You must then tell the API that it must call the callback when a new module is connected YAPI RegisterDeviceArrivalCallback deviceArrival Note that if modules are already connected when the callback is registered the callback is called for each of the already connected modules Triggering callbacks A cla
139. ed at the factory The values it returns are supposed to be reasonably correct in most cases There are however situations where external conditions can impact the measures The Yoctopuce API provides the mean to re caliber the values measured by your Yocto Volt You are not going to modify the hardware settings of the module but rather to transform afterwards the measures taken by the sensor This transformation is controlled by parameters stored in the flash memory of the module making it specific for each module This re calibration is therefore a fully software matter and remains perfectly reversible Before deciding to re calibrate your Yocto Volt module make sure you have well understood the phenomena which impact the measures of your module and that the differences between true values and measured values do not result from a incorrect use or an inadequate location of the module 112 www yoctopuce com 19 Advanced programming The Yoctopuce modules support two types of calibration On the one hand a linear interpolation based on 1 to 5 reference points which can be performed directly inside the Yocto Volt On the other hand the API supports an external arbitrary calibration implemented with callbacks 1 to 5 point linear interpolation These transformations are performed directly inside the Yocto Volt which means that you only have to store the calibration points in the module flash memory and all the correction computatio
140. em 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 www yoctopuce com 87 88 www yoctopuce com 17 Using the Yocto Volt with Java 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 17 1 Getting ready Go to the Yoctopuce web site and download the following items The Java programming library e The VirtualHub software for Windows Mac OS X or Linux depending on your OS 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 17 2 Control of the Voltage function A few lines of code are e
141. 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 inthe method onCreate of your application If the object passed as parameter is not of the correct type a YAPI Exception exception is generated Override public void onCreate Bundle savedInstanceState super onCreate savedinstanceState tey Pass the application Context to the Yoctopuce Library YAPI EnableUSBHost this Pacatch YAP TER xceptaon 1e i Log e Yocto e getLocalizedMessage Autorun 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 lt action android name android hardware usb action USB_DEVICE_ATTACHED gt in the section lt intent filter gt of the main activity The section lt activity gt must have a pointer to an XML file containing the list of USB modules which can run the application lt manifest xmlns android http schemas android com apk res android lt uses feature android name android hardware usb host gt
142. ence YAPI GetTickCount YAPI yGetTickCount Returns the current value of a monotone millisecond based time counter function yGetTickCount nodejs function GetTickCount function yGetTickCount u64 yGetTickCount u64 yGetTickCount function yGetTickCount u64 vo _ function yGetTickCount As Long ulong GetTickCount long GetTickCount def 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 132 www yoctopuce com 21 High level API Reference YAPI HandleEvents YAPI yHandleEvents Maintains the device to library communication channel function yHandleEvents errmsg function HandleEvents errmsg function yHandleEvents amp errmsg YRETCODE yHandleEvents string amp errmsg YRETCODE yHandleEvents NSError errmsg function yHandleEvents var errmsg string integer function yHandleEvents ByRef errmsg As String As YRETCODE YRETCODE HandleEvents ref string errmsg int HandleEvents def HandleEvents errmsg None 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 followi
143. er object 248 www yoctopuce com 21 High level API Reference datalogger get_friendlyName YDataLogger datalogger friendlyName Returns a global identifier of the data logger in the format MODULE_NAME FUNCT ION_NAME function get_friendlyName function get_friendlyName function get_friendlyName string get_friendlyName NSString friendlyName string get_friendlyName String get_friendlyName def get_friendlyName The returned string uses the logical names of the module and of the data logger if they are defined otherwise the serial number of the module and the hardware identifier of the data logger for exemple yCustomName relayl1 Returns a string that uniquely identifies the data logger using logical names ex MyCustomName relay1 On failure throws an exception or returns Y_FRIENDLYNAME_INVALID www yoctopuce com 249 21 High level API Reference datalogger get_functionDescriptor YDataLogger datalogger functionDescriptor Returns a unique identifier of type YFUN_DESCR corresponding to the function function get_functionDescriptor function get_functionDescriptor function get_functionDescriptor YFUN_DESCR get_functionDescriptor YFUN_DESCR functionDescriptor function get_functionDescriptor YFUN_DESCR function get_functionDescriptor As YFUN_DESCR YFUN_DESCR get_functionDescriptor String get_functionDescripto
144. erial VOLTAGE1 12345 api voltage logicalName Rather logically attributes can be modified in the same manner http 127 0 0 1 4444 bySerial VOLTAGE1 12345 api voltage logicalName myFunction You can find the list of available attributes for your Yocto Volt at the beginning of the Programming chapter Accessing Yoctopuce data logger through the REST interface 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 http 127 0 0 1 4444 bySerial VOLTAGE1 12345 dataLogger json Individual measures for any given stream can be obtained by appending the desired function identifier as well as start time of the stream 118 www yoctopuce com 20 Using with unsupported languages http 127 0 0 1 4444 bySerial VOLTAGE1 12345 dataLogger json id voltage amp utc 1389801080 20 3 Using dynamic libraries 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 libyapi armhf so Linux ARM HL 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 completel
145. es 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 Volt 2 http www yoctopuce com EN libraries php 24 www yoctopuce com 7 Programming general concepts www yoctopuce com 25 26 www yoctopuce com 8 Using the Yocto Volt in command line When you want to perform a punctual operation on your Yocto Volt 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 provided 8 1 Installing Download the command line API 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 Volt open a shell and start working by typing for example YVoltage any get_currentValu
146. eshooting 291 U UnregisterHub YAPI 144 Unsupported 117 UpdateDeviceList YAPI 145 UpdateDeviceList_async YAPI 146 V Value 284 Variants 54 VirtualHub 95 117 Visual 63 69 Voltage 20 28 31 39 49 57 64 70 77 83 89 98 193 W wait_async YDataLogger 269 wait_async YModule 191 wait_async YVoltage 234 Y YAPI 125 146 yCheckLogicalName 125 YDataLogger 237 269 YDataSet 272 282 yDisableExceptions 126 yEnableExceptions 127 yEnableUSBHost 128 yFindDataLogger 237 yFindModule 150 yFindVoltage 195 yFirstDataLogger 238 yFirstModule 151 yFirstVoltage 196 yFreeAPI 129 yGetAPIVersion 130 yGetTickCount 131 yHandleEvents 132 ylnitAPI 133 YMeasure 284 288 YModule 150 191 Yocto Volt 18 27 31 39 49 57 63 69 77 83 89 95 yPreregisterHub 134 yRegisterDeviceArrivalCallback 135 yRegisterDeviceRemovalCallback 136 yRegisterHub 137 yRegisterHubDiscoveryCallback 138 yRegisterLogFunction 139 ySelectArchitecture 140 ySetDelegate 141 ySetTimeout 142 ySleep 143 yUnregisterHub 144 yUpdateDeviceList 145 yUpdateDeviceList_async 146 YVoltage 195 234
147. eters in milliseconds Returns YAPI_SUCCESS when the call succeeds On failure throws an exception or returns a negative error code www yoctopuce com 261 21 High level API Reference datalogger load_async YDataLogger Preloads the data logger cache with a specified validity duration asynchronous version function load_async msValidity callback context 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 trafic 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 YAPT_SUCCESS context caller specific object that is passed as is to the callback function Returns nothing the result is provided to the callback 262 www yoctopuce com 21 High level API Reference datalogger nextDataLogger YDataLogger Continues t
148. ever touched directly by the API and is at disposal of the caller to store a context Returns the object stored previously by the caller www yoctopuce com 219 21 High level API Reference voltage isOnline YVoltage Checks if the voltage sensor is currently reachable without raising any error is __ function isOnline node js function isOnline php function isOnline cpp _ bool isOnline BOOL isOnline pas function isOnline boolean vb function isOnline As Boolean bool isOnline java boolean isOnline def isOnline If there is a cached value for the voltage sensor 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 voltage sensor Returns true if the voltage sensor can be reached and false otherwise 220 www yoctopuce com 21 High level API Reference voltage isOnline_async YVoltage Checks if the voltage sensor is currently reachable without raising any error asynchronous version function isOnline_async callback context function isOnline_async callback context If there is a cached value for the voltage sensor 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 ver
149. evices 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 The NAT filter advantages and disadvantages 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 www mysite com 192 168 0 1 64 136 20 37 BES 46 14 51 32 192 168 0 102 B 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 response Responses from request from LAN machines are routed 44 www yoctopuce com 10 Using Yocto Volt with PHP request i But requests from
150. ey are defined otherwise the serial number of the module and the hardware identifier of the voltage sensor for exemple MyCustomName relayl1 Returns a string that uniquely identifies the voltage sensor using logical names ex MyCustomName relay1 On failure throws an exception or returns Y_FRIENDLYNAME_ INVALID www yoctopuce com 205 21 High level API Reference voltage get_functionDescriptor YVoltage voltage functionDescriptor Returns a unique identifier of type YFUN_DESCR corresponding to the function function get_functionDescriptor function get_functionDescriptor function get_functionDescriptor YFUN_DESCR get_functionDescriptor YFUN_DESCR functionDescriptor function get_functionDescriptor YFUN_DESCR function get_functionDescriptor As YFUN_DESCR YFUN_DESCR get_functionDescriptor String get_functionDescriptor def 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_FUNCTIONDESCRIPTOR_INVALID 206 www yoctopuce com 21 High level API Reference voltage get_functionld YVoltage voltage functionld Returns the hardware identifier of the voltage sensor without reference to the module function get_functio
151. f get_resolution YVoltage target get_resolution pas ee ES The resolution corresponds to the numerical precision of the measures which is not always the same as the actual precision of the sensor Returns a floating point number corresponding to the resolution of the measured values On failure throws an exception or returns Y_RESOLUTION_INVALID www yoctopuce com 217 21 High level API Reference voltage get_unit voltage unit Returns the measuring unit for the measured value is __ function get_unit node js function get_unit php function get_unit string get_unit NSString unit function get_unit string v function get_unit As String cs string get_unit String get_unit def get_unit YVoltage target get_unit Returns a string corresponding to the measuring unit for the measured value On failure throws an exception or returns Y_UNIT_INVALID YVoltage 218 www yoctopuce com 21 High level API Reference voltage get_userData YVoltage voltage userData Returns the value of the userData attribute as previously stored using method set_userData function get_userData function get_userData function get_userData void get_userData void userData function get_userData Tobject function get_userData As Object object get_userData Object get_userData def get_userData This attribute is n
152. fers another possibility for error handling allowing you to create a robust program without needing to catch exceptions at every www yoctopuce com 61 12 Using Yocto Volt with Objective C line of code You simply need to call the yDisableExceptions 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 Y STATE INVALID value a get _currentValue method returns a Y 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
153. ff string logFmt from 0 to 1 average 2 0 00 3 Console WriteLine String Format logFmt summary get_startTimeUTC_asDateTime ToString timeFmt summary get_endTimeUTC_asDateTime ToString timeFmt summary get_averageValue sensor get_unit 2The YMeasure objects used by the data logger are exactly the same kind as those passed as argument to the timed report callbacks www yoctopuce com 111 19 Advanced programming Next calls to loadMore will retrieve measures Console WriteLine loading details int progress dom Console Write progress dataset loadMore while progress lt 100 All measures have now been loaded Mot Meds Ure decease taseme mea Ur eS foreach YMeasure m in details Console WriteLine String Format logFmt m get_startTimeUTC_asDateTime ToString timeFmt m get_endTimeUTC_asDateTime ToString timeFmt MG et averageValue Sensor gee mune yl I You will find a complete example demonstrating how to retrieve data from the logger for each programming language directly in the Yoctopuce library The example can be found in directory Examples Prog DataLogger Timestamp As the Yocto Volt does not have a battery it cannot guess alone the current time when powered on Nevertheless the Yocto Volt will automatically try to adjust its real time reference using the host to which it is connected in order to properly attach a timestamp to each measure in
154. fic object that is passed as is to the callback function Returns nothing www yoctopuce com 235 21 High level API Reference 21 4 DataLogger function interface Yoctopuce sensors include a non volatile memory capable of storing ongoing measured data automatically without requiring a permanent connection to a computer The DataLogger function controls the global parameters of the internal data logger In order to use the functions described here you should include lt script type text javascript src yocto_datalogger js gt lt script gt var yoctolib require yoctolib var YDataLogger yoctolib YDataLogger require_once yocto_datalogger php include yocto_datalogger h import yocto_datalogger h uses yocto_datalogger yocto_datalogger vb yocto_datalogger cs import com yoctopuce YoctoAPI YDataLogger from yocto_datalogger import Global functions yFindDataLogger func Retrieves a data logger for a given identifier yFirstDataLogger Starts the enumeration of data loggers currently accessible YDataLogger methods datalogger describe Returns a short text that describes the data logger in the form TYPE NAME SERIAL FUNCTIONID datalogger forgetAllDataStreams Clears the data logger memory and discards all recorded data streams datalogger get_advertisedValue Returns the current value of the data logger no more than 6 characters datalogger get_autoStart Ret
155. ficult 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 292 www yoctopuce com 23 Characteristics You can find below a summary of the main technical characteristics of your Yocto Volt module Width Length Weight USB connector Refresh rate Input impedance Measuring range Max voltage Accuracy AC Accuracy DC Sensitivity Supported Operating Systems Drivers API SDK Libraries USB TCP API SDK Libraries TCP only RoHS USB Vendor ID USB Device ID Suggested enclosure 20 mm 50 mm 6g micro B 10 Hz DC 331 KO 0 250 V DC AC 250 V 0 1V 3 0 01V 0 5 0 01V 0 2 Windows Linux Intel ARM Mac OS X Android no driver needed C Objective C C VB NET Delphi Python Java Android Javascript Node js PHP Java yes 0x24E0 0x001B YoctoBox Long Thick Black www yoctopuce com 293 23 Characteristics 294 www yoctopuce com
156. 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 5 2 Test of the module The first item to check is that your module is working well click on the serial number corresponding to your module This displays a window summarizing the properties of your Yocto Volt 1 www yoctopuce com EN virtualhub php 2 The interface was tested on FireFox 3 IE 6 Safari and Chrome It does not work with Opera www yoctopuce com 11 5 First steps VOLTAGE1 026C8 I VOLTAGE1 026C8 is a 20x50mm board he lt with an isolated voltage sensor aka voltmeter Kernel Serial VOLTAGE1 026C8 Product name Yocto Volt Logical name Product release 1 Firmware 6083 Consumption 89 mA Beacon Inactive tum on Luminosity 50 Sensors DC AC Currentvoltage 3 14 V ov Min voltage ov ov Max voltage 3 14 V 3 1v Misc Open API browser pop up Get user manual from yoctopuce com Close Properties of the Yocto Volt module This window allows you among other things to play with your module to check that it is working the measured values are indeed displayed in real time 5 3 Configuration When in the module list you click on the configure button corresponding to your module the configuration window is displayed VOLTAGE1 026C8 Edit parameters for device VOLTAGE 1 026C8 and click o
157. fluence of euphoriant substances Beware of family reunions they are known for their large amount of die offs among the DIY population Don t work alone If things go bad you can then hope to be rescued fast enough Dangerous components Some components of the Yocto Volt module find themselves directly on the measured voltage Make sure never to touch them when the module is powered on These components must never be in contact with a conductive component of your project look out for metallic enclosures Even more importantly make sure that your project end user can never touch these components even accidentally a0 oj e a o EURE Potentially dangerous components of the Yocto Volt module www yoctopuce com www yoctopuce com 4 Direct current vs alternating current The Yocto Volt module is able to measure a direct voltage as well as an alternating voltage You can typically measure a direct voltage on the terminals of a battery or at the output of a stabilized power supply for electronic equipment It is supposed to stay relatively stable over time Direct voltage stable over time An alternating voltage is a voltage which periodically varies over time The most typical example is the voltage of the mains In Europe the voltage of the mains varies between 325v and 325v about 50 times per second for an typical value of 220V A dynamo such as the one on your bike also produces alternating current
158. for this sensor for a specified time interval function get_recordedData startTime endTime function get_recordedData startTime endTime function get_recordedData startTime endTime YDataSet get_recordedData s64 startTime s64 endTime YDataSet recordedData s64 startTime S64 endTime function get_recordedData startTime int64 endTime int64 TYDataSet function get_recordedData As YDataSet YDataSet get_recordedData long startTime long endTime YDataSet get_recordedData long startTime long endTime def get_recordedData startTime endTime YVoltage target get_recordedData startTime endTime The measures will be retrieved from the data logger which must have been turned on at the desired time See the documentation of the DataSet class for information on how to get an overview of the recorded data and how to load progressively a large set of measures from the data logger This function only works if the device uses a recent firmware as DataSet objects are not supported by firmwares older than version 13000 a Parameters startTime the start of the desired measure time interval as a Unix timestamp i e the number of seconds since January 1 1970 UTC The special value 0 can be used to include any meaasure without initial limit endTime the end of the desired measure time interval as a Unix timestamp i e the number of seconds since January 1 1970 UTC The special value 0 can be used to include any meaasur
159. from YAPI SUCCESS and errmsg contains the error message YVoltage FindVoltage The YVoltage FindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel voltage YVoltage FindVoltage VOLTAGE1 123456 MyFunction voltage YVoltage FindVoltage MyModule voltagel voltage YVoltage FindVoltage MyModule MyFunction voltage YVoltage FindVoltage MyFunction YVoltage FindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by YVoltage FindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get_currentValue method of the object returned by YVoltage FindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts A real example Launch Python and open the corresponding sample script provided in the directory Exam
160. function get_usbBandwidth function get_usbBandwidth function get_usbBandwidth Y_USBBANDWIDTH_enum get_usbBandwidth Y_USBBANDWIDTH_enum usbBandwidth function get_usbBandwidth Integer function get_usbBandwidth As Integer int get_usbBandwidth int get_usbBandwidth def get_usbBandwidth YModule target get_usbBandwidth Returns either Y_USBBANDWIDTH_SIMPLE or Y_USBBANDWIDTH_DOUBLE according to the number of USB interfaces used by the module On failure throws an exception or returns Y_USBBANDWIDTH_INVALID www yoctopuce com 175 21 High level API Reference module gt get_usbCurrent YModule module gt usbCurrent Returns the current consumed by the module on the USB bus in milli amps function get_usbCurrent function get_usbCurrent function get_usbCurrent int get_usbCurrent int usbCurrent pas function get_usbCurrent Longint v _ function get_usbCurrent As Integer int get_usbCurrent int get_usbCurrent def get_usbCurrent 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 Y_USBCURRENT_INVALID 176 www yoctopuce com 21 High level API Reference module get_userData YModule module gt userData Returns the value of the userData attribute as previously stored
161. ge of the sensor The device will automatically perform a linear interpolation of the error correction between specified points Remember to call the saveToFlash method of the module if the modification must be kept For more information on advanced capabilities to refine the calibration of sensors please contact support yoctopuce com Parameters rawValues array of floating point numbers corresponding to the raw values returned by the sensor for the correction points refValues array of floating point numbers corresponding to the corrected 198 www yoctopuce com 21 High level API Reference voltage describe YVoltage Returns a short text that describes the voltage sensor in the form TYPE NAME SERIAL FUNCTIONID function describe function describe function describe string describe NSString describe function describe string function describe As String string describe String describe def 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 relayl RELAYLO1 123456 relayl if the module is already connected or Relay BadCustomeName relayl unresolved if the module has not yet been connec
162. get_currentRawValue As Double double get_currentRawValue double get_currentRawValue def get_currentRawValue YVoltage target get_currentRawValue Returns a floating point number corresponding to the uncalibrated unrounded raw value returned by the sensor YVoltage On failure throws an exception or returns Y_CURRENTRAWVALUE_INVALID www yoctopuce com 201 21 High level API Reference voltage get_currentValue voltage currentValue Returns the current measured value function get_currentValue function get_currentValue function get_currentValue double get_currentValue double currentValue function get_currentValue double function get_currentValue As Double double get_currentValue double get_currentValue def get_currentValue YVoltage target get_currentValue Returns a floating point number corresponding to the current measured value On failure throws an exception or returns Y_CURRENTVALUE_INVALID YVoltage 202 www yoctopuce com 21 High level API Reference voltage get_errorMessage YVoltage voltage errorMessage Returns the error message of the latest error with the voltage sensor function get_errorMessage function get_errorMessage function get_errorMessage string get_errorMessage NSString errorMessage function get_errorMessage string function get_errorMessage As String string get_errorMessage
163. gument 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 an YMeasure object describing the new advertised value 226 www yoctopuce com 21 High level API Reference voltage registerValueCallback YVoltage Registers the callback function that is invoked on every change of advertised value function registerValueCallback callback function registerValueCallback callback function registerValueCallback callback int registerValueCallback YVoltageValueCallback callback int registerValueCallback YVoltageValueCallback callback function registerValueCallback callback TY VoltageValueCallback Longint function registerValueCallback As Integer int registerValueCallback ValueCallback callback int registerValueCallback UpdateCallback callback def 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 adver
164. h 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 Y STATE INVALID value a get _currentValue method returns a Y 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 www yoctopuce com 75 76 www yoctopuce com 15 Using Yocto Volt with Delphi 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 something Delphi libraries are prov
165. h allows you to access your module in the same way a file name allows you to access its content A logical name has a maximum length of 19 characters Authorized characters are A Z a z 0 9 _ and If you assign the same logical name to two modules connected to the same computer and you try to access one of them through this logical name behavior is undetermined you have no way of knowing which of the two modules answers Luminosity This parameter allows you to act on the maximal intensity of the leds of the module This enables you if necessary to make it a little more discreet while limiting its power consumption Note that this parameter acts on all the signposting leds of the module including the Yocto led If you connect a module and no led turns on it may mean that its luminosity was set to zero Logical names of functions Each Yoctopuce module has a serial number and a logical name In the same way each function on each Yoctopuce module has a hardware name and a logical name the latter can be freely chosen by the user Using logical names for functions provides a greater flexibility when programming modules The two functions provided by the Yocto Volt module are the VoltageDC and VoltageAC functions Simply click on the corresponding rename button to assign a new logical name to one of the functions www yoctopuce com 13 14 www yoctopuce com 6 Assembly and connections This chapter provides importa
166. h memory the correct number of calibration points the corresponding callback is called to correct the value before returning it enabling thus a perfectly transparent measure correction www yoctopuce com 115 116 www yoctopuce com 20 Using with unsupported languages 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 20 1 Command line 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 20 2 VirtualHub and HTTP GET The VirtualHub is availabl
167. he enumeration of data loggers started using yFirstDataLogger function nextDataLogger function nextDataLogger function nextDataLogger YDataLogger nextDataLogger YDataLogger nextDataLogger function nextDataLogger TYDataLogger function nextDataLogger As YDataLogger YDataLogger nextDataLogger YDataLogger nextDataLogger def nextDataLogger Returns a pointer toa YDataLogger object corresponding to a data logger currently online or a nul pointer if there are no more data loggers to enumerate www yoctopuce com 263 21 High level API Reference datalogger registerValueCallback YDataLogger Registers the callback function that is invoked on every change of advertised value is__ function registerValueCallback callback node js function registerValueCallback callback php_ function registerValueCallback callback int registerValueCallback YDataLoggerValueCallback callback int registerValueCallback YDataLoggerValueCallback callback pas function registerValueCallback callback TYDataLoggerValueCallback LongInt vb function registerValueCallback As Integer int registerValueCallback ValueCallback callback int registerValueCallback UpdateCallback callback def 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
168. he 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 gt 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 nextModule Continues the module enumeration started using yFirstModule module gt reboot secBeforeReboot Schedules a simple module reboot after the given number of seconds module gt revertFromFlash Reloads the settings stored in the nonvolatile memory as when the module is powered on module gt saveToFlash Saves current settings in the nonvolatile memory of the module module set_beacon newval Turns on or off the module localization beacon www yoctopuce com 149 21 High level API Reference 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_usbBandwidth newval Changes the number of USB interfaces used by the module
169. he timestamp may have a fractional part Returns an floating point number corresponding to the number of seconds between the Jan 1 1970 UTC and the beginning of this measure www yoctopuce com 289 290 www yoctopuce com 22 Troubleshooting 22 1 Linux and USB 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 Virtua Hub for Linux archive there are two rule examples which you c
170. hile yGetTickCount now lt 3000 exire LN ies ink Mein nt eiee Const char w aro 1 string errmsg string target YVoltage sensor YVoltage sensorAC YVoltage sensorDC YModule Ty de arge lt 2 usage target string argv 1 YAPI DisableExceptions Setup the API to use local USB devices ee VAP RegusiterHubi usbi a erans 9 YAP VSUCEHOS Ns Gana lt lt Aeiio Gieidenes V lt lt eane lt lt iaielllp return 1 ir target Wanye retreive any voltage sensor can be AC or DC sensor YVoltage FirstVoltage if sensor NULL cerr lt lt No module connected Check cable lt lt endl exit 1 else sensor YVoltage FindVoltage target voltagel we need to retreive both DC and AC voltage from the device if sensor gt isOnline m sensor gt get_module sensorDC YVoltage FindVoltage m gt get_serialNumber voltagel sensorAC YVoltage FindVoltage m gt get_serialNumber voltage2 else cerr lt lt No module connected Check cable lt lt endl exit Ll while 1l if sensorDC gt isOnline cout lt lt Module disconnected lt lt endl break cout lt lt Voltage De lt lt SenSOrEDe Get eur renta lme Gua evn POUL lt lt AC ee Sens OrAC og ci Cur rent Value ie Basin COuUEN lt lt press CENI GC Eo exi e earen YAPI Sleep 1000 errmsg return 0 11 2 Control of the
171. hout requiring a permanent connection to a computer The DataLogger function controls the global parameters of the internal data logger logicalName Character string containing the logical name of the data logger 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 data logger directly If two data loggers 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 advertisedValue Short character string summarizing the current state of the data logger that is automatically advertised up to the parent hub For a data logger the advertised value is its recording state ON or OFF www yoctopuce com 21 7 Programming general concepts currentRunIndex Current run number corresponding to the number of time the module was powered on with the dataLogger enabled at some point timeUTC Current UTC time in case it is desirable to bind an absolute time reference to the data stored by the data logger This time must be set up by software recording Activation state of the data logger The data logger can be enabled and disabled at will using this attribute but its state on power on is determined by the autoStart persistent attribute autoStart Automatic start of the data logger on power o
172. ial GET serial Lf eserial f 9 Check if a specified module is available online Ssensor yFindVoltage serial voltagel Lf Ssensor gt isOnline die Module not connected check serial and USB cable else or use any connected module suitable for the demo Ssensor yFirstVoltage ie GSM nUMsIa S sensor eat die No module connected check USB cable else serial sensor gt module gt get_serialnumber Print Module to use lt input name serial value Sserial gt lt br gt if Ssensor gt isOnline SsensorDC yFindVoltage serial voltagel SsensorAC yFindVoltage S serial voltage2 SDC SsensorDC gt get_currentValue SAC sensorAC gt get_currentValue Pranti Voltage De Spe V PE 5 EnC y Sore trigger auto refresh after one second Print lt script language javascript1 5 type text JavaScript gt n Print setTimeout window location reload 1000 Pe ime US SCEI PENNA eS lt BODY gt lt HTML gt 10 3 Control of the module part 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 lt HTML gt lt HEAD gt lt TITLE gt Module Control lt TITLE gt lt HEAD gt lt BODY gt lt FORM method get gt lt php include yocto_api php Use explicit error handling r
173. ibrary 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 www yoctopuce com 81 15 Using Yocto Volt with Delphi 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 i1sOnline 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 e If your code catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang
174. icating 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 support Current sensor Each Yocto module is able to measure its own current consumption on the USB bus Current supply on a USB bus being quite critical this functionality can be of great help You can only view the current consumption of a module by software Serial number Each Yocto module has a unique serial number assigned to it at the factory For Yocto Volt modules this number starts with VOLTAGE1 The module can be software driven using this serial number The serial number cannot be modified Logical name The logical name is similar to the serial number it is a supposedly unique character string which allows you
175. ided 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 e If your code catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the problem happened and view the explanatory message linked to the exception e Otherwise the exception makes your program crash bang 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 yDisableExceptions function to commute the library to a mode where exceptions for all
176. ided not as VCL components but directly as source files These files are compatible with most Delphi versions 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 15 1 Preparation Go to the Yoctopuce web site and download the Yoctopuce Delphi libraries Uncompress everything in a directory of your choice add the subdirectory sources in the list of directories of Delphi libraries By default the Yoctopuce Delphi library uses the yapi di 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 15 2 Control of the Voltage function 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 program helloworld SAPPTYPE CONSOLE USOS Syst iLSs Windows yocto_ api yocto voltage 1 Actually Borland provided free versions for personal use of Delphi 2006 and 2007 Look for them on the Internet you may still be able to download them 2 Delphi
177. 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 program savesettings SAPPTYPE CONSOLE uses SVa UEMS yocto_ api const serial VOLTAGE1 123456 use serial number or logical name var module TYModule ering ss Stern newname string begin Setup the API to use local USB devices if yRegisterHub usb errmsg lt gt YAPI SUCCESS then begin Write RegisterHub error errmsg exit end module yFindModule serial if not module isOnline then begin writeln Module not connected check identification exit and USB cable 80 www yoctopuce com 15 Using Yocto Volt with Delphi end Writeln Current logical name module get_logicalName Write Enter new name Readln newname if not yCheckLogicalName newname then begin Writeln invalid logical name exit end module set_logicalName newname module saveToFlash Writeln logical name is now module get_logicalName end Warning the number of write cycles of the nonvolatile memory of the module is limited When this limit
178. ime PO duke gt Ge emu limen i 000m lt lt T sech lt lt encu coti lt SUSE Current lt lt nodule gt getwusbCurreni lt lt Wma lt lt en cill cout lt lt Logs lt lt endl lt lt module gt get_lastLogs lt lt endl else cout lt lt argv 1 lt lt not connected check identification and USB cable lt lt endl i return 0 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 Changing the module settings 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 include lt iostream gt include lt stdlib h gt include yocto_api h using namespace std static void usage const char exe 52 www yoctopuce com 11 Using Yocto Volt with
179. in more details YAPI RegisterHub 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 YVoltage FindVoltage The YVoltage FindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel voltage YVoltage FindVoltage VOLTAGE1 123456 MyFunction voltage YVoltage FindVoltage MyModule voltagel voltage YVoltage FindVoltage MyModule MyFunction voltage YVoltage FindVoltage MyFunction YVoltage FindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by YVoltage FindVoltage allows you to know if the corresponding module is present
180. ine args 0 not connected check identification and USB cable 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 Changing the module settings 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 using System USING Svs Cem Collections Generic using System Linqg using System Text namespace ConsoleApplicationl class Program static void usage string execname System AppDomain CurrentDomain FriendlyName Console WriteLine Usage Console WriteLine usage demo lt serial or logical name gt lt new logical name gt System Threading Thread Sleep 2500 Environment Exit 0 static void Main string a
181. ing System Text namespace ConsoleApplicationl ellass Program static void usage string execname System AppDomain CurrentDomain FriendlyName Console WriteLine Usage Console WriteLine execname lt serial or logical name gt ON OFF System Threading Thread Sleep 2500 Environment Exit 0 static void Main string args YModule m string errmsg if YAPI RegisterHub usb ref errmsg YAPI SUCCESS Console WriteLine RegisterHub error errmsg Environment Exit 0 alae elaetojis kengt him usage m YModule FindModule args 0 use serial or logical name if m isOnline if args Length gt 2 te args i tovipeer ON Sem set beacon YModule BEACON RON I 1E args HC ToUpper OK m set beacon YModule SE ACONROEE s s Console WriteLine serial mage emcee clNumoerai si Console WriteLine logical name m get_logicalName Console WriteLine luminosity War Wintec liwiialiqueysilies7 E TOSE iTO Console Write beacon ue if m get_beacon YModule BEACON_ ON Console WriteLine ON else Console WriteLine OFF Console WriteLine upTime Wr io Gis omine y AOI oscene a V SECH Console Wri teinne WUSB current U m get usbCUnrent k Tostring os mar iy Console WriteLine Logs r n m get_lastLogs 72 www yoctopuce com 14 Using Yocto Volt with C else Console WriteL
182. int 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 mod
183. ion get_firmwareRelease function get_firmwareRelease string get_firmwareRelease NSString firmwareRelease function get_firmwareRelease string function get_firmwareRelease As String string get_firmwareRelease String get_firmwareRelease def get_firmwareRelease 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 Y_F TRMWARERELEASE_INVALID 162 www yoctopuce com 21 High level API Reference module get_hardwareld module gt hardwareld Returns the unique hardware identifier of the module function get_hardwareld function get_hardwareld function get_hardwareld string get_hardwareld NSString hardwareld function get_hardwareld As String string get_hardwareld String get_hardwareld def get_hardwareld YModule The unique hardware identifier is made of the device serial number followed by string module Returns a string that uniquely identifies the module www yoctopuce com 163 21 High level API Reference module gt get_icon2d YModule module gt icon2d Returns the icon of the module function get_icon2d node js function get_icon2d function get_icon2d string get_icon2d NSData icon2d function get_icon2d TByteArray function get_icon2d As Byte def get_icon2d
184. 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 Listing the modules 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 program inventory SAPPTYPE CONSOLE Wises Sysutils yocto_api var module TYModule errmsg string begin Setup the API to use local USB devices if yRegisterHub usb errmsg lt gt YAPI SUCCESS then begin Write RegisterHub error errmsg exit end Writeln Device list module yFirstModule while module lt gt nil do begin Writeln module get_serialNumber module get_productName module module nextModule end end 15 4 Error handling 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 l
185. 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 11 1 Control of the Voltage function A few lines of code are enough to use a Yocto Volt Here is the skeleton of a C code snipplet to use the Voltage function include yocto_api h include yocto_ voltage h Lao oll String errmsg YVoltage voltage Get access to your device connected locally on USB for instance yRegisterHub usb errmsg voltage yFindVoltage VOLTAGE1 123456 voltagel 1 http www microsoft com visualstudio en us products 2010 editions visual cpp express www yoctopuce com EN libraries php www yoctopuce com 49 11 Using Yocto Volt with C Hot plug is easy just check that the device is online if voltage gt isOnline 7 USC VOUE
186. ith Android public void toggleBeacon View view if module null Cerun boolean on cry 4 Ie om a Switch view isChecked module setBeacon YModule BEACON_ ON else module setBeacon YModule BEACON OFF i p earen YONI ICC oieseum 4 e printStackTrace 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 Changing the module settings 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 package com yoctopuce doc_ examples import import import import import import import import import import import import import public android app Activity android os Bundle android view
187. l your Yocto Volt in an optional enclosure 4 www yoctopuce com 2 Presentation 1 Micro B USB socket 4 Measure input positive 2 Yocto button 5 Measure input negative 3 Yocto led 2 1 Common elements All Yocto modules share a number of common functionalities USB connector Yoctopuce modules all come with a micro B USB socket The corresponding cables are not the most common but the sockets are the smallest available Warning the USB connector is simply soldered in surface and can be pulled out if the USB plug acts as a lever In this case if the tracks stayed in position the connector can be soldered back with a good iron and using flux to avoid bridges Alternatively you can solder a USB cable directly in the 1 27mm spaced holes near the connector Yocto button The Yocto button has two functionalities First it can activate the Yocto beacon mode see below under Yocto led Second if you plug in a Yocto module while keeping this button pressed you can www yoctopuce com 2 Presentation then reprogram its firmware with a new version Note that there is a simpler Ul based method to update the firmware but this one works even in case of severely damaged firmware Yocto led Normally the Yocto led is used to indicate that the module is working smoothly The Yocto led then emits a low blue light which varies slowly mimicking breathing The Yocto led stops breathing when the module is not commun
188. lar 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 acces control has been activated on the hub virtual or not you want to reach the URL parameter should look like http username password adresse 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 138 www yoctopuce com 21 High level API Reference YAPI RegisterHubDiscoveryCallback YAPI yRegisterHubDiscoveryCallback Register a callback function to be called each time a network hub or a VirtualHub is detected on the local network void RegisterHubDiscoveryCallback NewHubCallback callback Parameters callback a procedure taking a two string as parameter or null www yoctopuce com 139 21 High level API Reference YAPI RegisterLogFunction YAPI yRegisterLogFunction Registers a log callback function void yRegisterLogFunction yLogFunction logfun void yRegisterLogFunction yLogCallback logfun procedure yRegisterLogFunction logfun yLogFunc
189. le def get_module YVoltage If the function cannot be located on any module the returned instance of YModu1e is not shown as on line Returns an instance of YModule www yoctopuce com 213 21 High level API Reference voltage get_module_async YVoltage voltage module_async Gets the YModule object for the device on which the function is located asynchronous version function get_module_async callback context 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 Javascript 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 214 www yoctopuce com 21 High level API Reference voltage get_recordedData YVoltage voltage recordedData Retrieves a DataSet object holding historical data
190. le get_serialNumber module serialNumber Returns the serial number of the module as set by the factory function get_serialNumber function get_serialNumber function get_serialNumber string get_serialNumber NSString serialNumber function get_serialNumber string function get_serialNumber As String string get_serialNumber String get_serialNumber def get_serialNumber 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 Y_SERTALNUMBER_INVALID YModule www yoctopuce com 173 21 High level API Reference module get_upTime YModule module upTime Returns the number of milliseconds spent since the module was powered on is _ function get_upTime node js function get_upTime php_ function get_upTime s64 get_upTime s64 upTime function get_upTime int64 v _ function get_upTime As Long long get_upTime long get_upTime def get_upTime 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 Y_UPTIME_INVALID 174 www yoctopuce com 21 High level API Reference module get_usbBandwidth YModule module usbBandwidth Returns the number of USB interfaces used by the module
191. libraries are regularly tested with Delphi 5 and Delphi XE2 www yoctopuce com EN libraries php 4 Use the Tools Environment options menu www yoctopuce com 77 15 Using Yocto Volt with Delphi Procedure usage begin writeln demo lt serial number gt writeln demo lt logical_ name gt writeln demo any sleep 2500 Halt end Procedure die msg string begin writeln msg check USB cable inealiter end var errmsg PSREN target ESC sensor TYVoltage sensorDC TYVoltage sensorAC TYVoltage m TyModule pegin if paramcount lt 1 then usage target paramstr 1 Setup the API to use local USB devices Ine RS SieSidsible wisig Cusine lt gt YARS USERS S Warsia begin WriteLn RegisterHub error errmsg Paley End if target any then begin retreive any voltage sensor can be AC or DC sensor yFirstVoltage If sensor nil Then Die No module connected end else sensor yFindVoltage target voltagel m nal sensorDC nil sensorAC nil we need to retreive both DC and AC voltage from the device If sensor isOnline Then begin Me Sscnsonr geramodullen iy sensorDe j yHindVolitage m get serrallNumber lt volltageil i sensorAC yFindVoltage m get_serialNumber voltage2 end else Die Module not connected let s poll TASOSENE If Not m isOnline Then Die Module not connected Werte ples ap
192. 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 Supported hardware The library is tested and validated on the following machines e Samsung Galaxy S3 e Samsung Galaxy Note 2 e Google Nexus 5 e Google Nexus 7 e Acer Iconia Tab A200 e Asus Tranformer Pad TF300T e Kurio 7 If your
193. mation as in the exceptions when they are active 82 www yoctopuce com 16 Using the Yocto Volt with Python 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 site 16 1 Source files The Yoctopuce library classes 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 16 2 Dynamic library 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 Th
194. meter 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 d i DLL to read and then update the luminosity of a module www yoctopuce com 119 20 Using with unsupported languages Ar Dil functions Inport function yapilInitAPI mode integer errmsg k pansichar sinteger cdecl external yapi dill name yapilInitAPI function yapilUpdateDevicelist fonce integer ernrmsg pansichar integer icdecl external yapi dll name yapiUpdateDevi
195. module part 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 include lt iostream gt include lt stdlib h gt www yoctopuce com 51 11 Using Yocto Volt with C include yocto_ api h using namespace std static void usage const char exe cout lt lt usage lt lt exe lt lt lt serial or logical name gt ON OFF lt lt endl exit 1 ine mann Ime arge const char aroni I string errmsg Setup the API to use local USB devices if yRegisterHub usb errmsg YAPI SUCCESS Cene lt lt Wikeyenisicehalsible erior W lt lt uriamsie lt lt meil return 1 Iiiardge 2 usage argv 0 YModule module yFindModule argv 1 use serial or logical name if module gt isOnline me ebeoe 2 if string argv 2 ON else module gt set_beacon Y_ BEACON ON module gt set_beacon Y BEACON OFF cout lt lt serial w x lt lt module gt get serialNumber i lt lt endl cout lt lt logical name lt lt module gt get_logicalName lt lt endl cout lt lt luminosity lt lt module gt get_luminosity lt lt endl cout lt lt beacon a if module gt get_beacon Y_BEACON_ON Cou lt lt NON lt lt enal else cour lt lt OFF lt endl cout lt lt uup r
196. mp errmsg YRETCODE ySleep unsigned ms_duration string amp errmsg YRETCODE ySleep unsigned ms_duration NSError errmsg function ySleep ms_duration integer var errmsg string integer function ySleep ByVal ms_duration As Integer ByRef errmsg As String As Integer int Sleep int ms_duration ref string errmsg int Sleep long ms_duration def Sleep ms_duration errmsg None This function implements a passive waiting loop meaning that it does not consume CPU cycles significatively 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 144 www yoctopuce com 21 High level API Reference YAPI UnregisterHub YAPI yUnregisterHub Setup the Yoctopuce library to no more use modules connected on a previously registered machine with RegisterHub function yUnregisterHub url function UnregisterHub url function yUnregisterHub url void yUnregisterHu
197. multiplication by a given factor between two points If you provide the two points a b and c d the function result is multiplied d b c a in the a c range and shifted so that when the value read by the sensor is a or c the voltage1 function returns respectively b and d Outside of the a c range the values are simply shifted so as to preserve the continuity of the measures an increase of 1 on the value read by the sensor induces an increase of 1 on the returned value www yoctopuce com 113 19 Advanced programming o se Dr 20 v ES 3 e z ey Pa 15 8 O O 10 5 A sensor value i 5 10 15 20 25 30 Measure correction with the two calibration points 10 5 and 25 10 The code allowing you to program this calibration is very similar to the preceding code example Double ValuesBefore 10 25 Double ValuesAfter 5 10 YVoltage f YVoltage FirstVoltage f calibrateFromPoints ValuesBefore ValuesAfter f get_module saveToFlash Note that the values before correction must be sorted in a strictly ascending order otherwise they are simply ignored 3 to 5 point correction 3 to 5 point corrections are only a generalization of the 2 point method allowing you to create up to 4 correction ranges for an increased precision These ranges cannot be disjoint RO 5 oO 20 T we f gt amp G ie k gs 158 S O O 10 wos corr ae 5 sensor value i 5 10 15 20 2
198. n Setting this attribute ensures that the data logger is always turned on when the device is powered up without need for a software command clearHistory Attribute that can be set to true to clear recorded data 7 6 What interface Native DLL or Service There are several methods to control you Yoctopuce module by software Native control 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 Native control by DLL 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 22 www yoctopuce com 7 Programmi
199. n 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 using System Using oys tem Collections Generic using System Linq using System Text namespace ConsoleApplicationl class Program static void Main string args i YModule m string errmsg if YAPI RegisterHub usb ref errmsg YAPI SUCCESS Console WriteLine RegisterHub error errmsg Environment Exit 0 Console WriteLine Device list m YModule FirstModule while m null1 Neonsollen We vEcinine Mm GatmseritcuNumber i e prode EN ame st iu k m m nextModule 14 5 Error handling 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
200. n the Save button Serial VOLTAGE1 026C8 Product name Yocto Volt Firmware 6083 Grade Logical name Luminosity id signal leds only Device functions Each function of the device has a physical name and a logical name You can change the logical name using the rename button VOLTAGE 1 026C8 dataLogger VOLTAGE1 026C8 voltage1 VOLTAGE 1 026C8 voltage2 Save Cancel Yocto Volt module configuration Firmware The module firmware can easily be updated with the help of the interface To do so you must beforehand have the adequate firmware on your local disk Firmware destined for Yoctopuce modules are available as byn files and can be downloaded from the Yoctopuce web site To update a firmware simply click on the upgrade button on the configuration window and follow the instructions If the update fails for one reason or another unplug and re plug the module and start the update process again This solves the issue in most cases If the module was unplugged while it was being reprogrammed it does probably not work anymore and is not listed in the interface However it is always possible to reprogram the module correctly by using the Virtual Hub software in command line 3 www yoctopuce com EN virtualhub php 4 More information available in the virtual hub documentation 12 www yoctopuce com 5 First steps Logical name of the module The logical name is a name that you choose whic
201. nction the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once var voltage var voltage var voltage var voltage var volitage yFindVoltage VOLTAGE1 123456 voltagel yFindVoltage VOLTAGE1 123456 MyFunction yFindVoltage MyModule voltagel yFindVoltage MyModule MyFunction yFindVoltage MyFunction yFindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by yFindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get _currentValue method of the object returned by yFindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts A real example Open your preferred text editor copy the code sample below save it in the same directory as the Yoctopuce library files and then use your preferred web browser to access this page The code is also provided in the directory Examples Doc GettingStarted Yocto Volt 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 The example is coded to be used either from a web server or directly by opening the file on the local machine Note that this late
202. nction the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once voltage yFindVoltage VOLTAGE1 123456 voltagel voltage yFindVoltage VOLTAGE1 123456 MyFunction voltage yFindVoltage MyModule voltagel voltage yFindVoltage MyModule MyFunction voltage yFindVoltage MyFunction yFindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by yFindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get _currentValue method of the object returned by yFindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts 4 Remember to change the filter of the selection window otherwise the DLL will not show 64 www yoctopuce com 13 Using Yocto Volt with Visual Basic NET A real example Launch Microsoft VisualBasic and open the corresponding sample project provided in the directory Examples Doc GettingStarted Yocto Volt 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 Module Modulel Private Sub Usage Dim execname System AppDomain CurrentDomain FriendlyName Console WriteLine Usage
203. ncy string newval int set_reportFrequency String newval def set_reportFrequency newval YVoltage target set_reportFrequency newval The frequency can be specified as samples per second as sample per minute for instance 15 m or in samples per hour eg 4 h To disable timed value notifications for this function use the value OFF Parameters newval a string corresponding to the timed value notification frequency for this function Returns YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code 232 www yoctopuce com 21 High level API Reference voltage set_resolution YVoltage voltage setResolution Changes the resolution of the measured values function set_resolution newval function set_resolution newval function set_resolution newval int set_resolution double newval int setResolution double newval function set_resolution newval double integer function set_resolution ByVal newval As Double As Integer int set_resolution double newval int set_resolution double newval def set_resolution newval YVoltage target set_resolution newval The resolution corresponds to the numerical precision when displaying value It does not change the precision of the measure itself Parameters newval a floating point number corresponding to the resolution of the measured values Returns YAPI_SUCCESS if the call succee
204. ndVoltage MyModule MyFunction yFindVoltage MyFunction yFindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by yFindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get _currentValue method of the object returned by yFindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts A real example Launch your C environment and open the corresponding sample project provided in the directory Examples Doc GettingStarted Yocto Volt 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 tinelude Vy OGLOmap hi include yocto voltage h include lt iostream gt include lt stdlib h gt using namespace std 50 www yoctopuce com 11 Using Yocto Volt with C static void usage void cout lt lt usages demo lt serilal number lt lt endl cout lt lt a demo lt logical_ name gt lt lt endl Cette demo any use any discovered device lt lt endl u64 now yGetTickCount dirty active wait loop w
205. ndle import android util Log import android view View import android widget AdapterView import android widget AdapterView OnItemSelectedListener import android widget ArrayAdapter import android widget Spinner import android widget Switch import android widget TextView import com yoctopuce YoctoAPI YAPI import com yoctopuce YoctoAPI YAPI Exception import com yoctopuce YoctoAPI YModule public class ModuleControl extends Activity implements OnItemSelectedListener private ArrayAdapter lt String gt aa private YModule module null Override public void onCreate Bundle savedInstanceState super onCreate savedInstanceState setContentView R layout modulecontrol Spinner my spin Spinner findViewById R id spinner1 my spin setOnItemSelectedListener this 100 www yoctopuce com 18 Using the Yocto Volt with Android aa new ArrayAdapter lt String gt this android R layout simple spinner item aa setDropDownViewResource android R layout simple spinner dropdown item my spin setAdapter aa Override protected void onStart super onStart try aa clear YAPI EnableUSBHost this YAPI RegisterHub usb YModule r YModule FirstModule while r null String hwid r get_hardwareId aa add hwid r r nextModule peCarCh a VAP TEE xc epielOnmc ia e printStackTrace refresh Spinner with detected relay aa notifyDa
206. ned only once voltage yFindVoltage VOLTAGE1 123456 voltagel voltage yFindVoltage VOLTAGE1 123456 MyFunction voltage yFindVoltage MyModule voltagel voltage yFindVoltage MyModule MyFunction voltage yFindVoltage MyFunction yFindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by yFindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get _currentValue method of the object returned by yFindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts 15 3 Control of the module part 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 program modulecontrol SAPPTYPE CONSOLE uses Syste t lsn yocto_api const serial VOLTAGE1 123456 use serial number or logical name procedure refresh module Tymodule begin if module isOnline then begin Were Ima Writeln Serial 7 a modulerge reser Numbers k Writeln Logical name module get_logicalName Writeln Luminosity intToStr module get_luminosity Write Beacon SN BE module get_beacon Y_ BEACON ON then Writeln on else W
207. newname As String Dim m As YModule If argv Length lt gt 3 Then usage REM Setup the API to use local USB devices If yRegisterHub usb errmsg lt gt YAPI_SUCCESS Then Console WriteLine RegisterHub error errmsg End End If m yFindModule argv 1 REM use serial or logical name If m isOnline Then newname argv 2 If Not yCheckLogicalName newname Then Console WriteLine Invalid name newname End End If m set_logicalName newname m saveToFlash REM do not forget this Console Write Module serial im get serial Numbex Console Write name m get_logicalName Else Console Write not connected check identification and USB cable End Lf End Sub End 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 Listing the modules 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 i
208. ng function functionld ByVal functionIndex As Integer As String string functionld int functionIndex def functionld functionIndex Parameters functionIndex the index of the function for which the information is desired starting at O 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 156 www yoctopuce com 21 High level API Reference module functionName YModule Retrieves the logical name of the nth function on the module function functionName functionIndex function functionName functionIndex function functionName functionIndex string functionName int functionIndex NSString functionName int functionindex function functionName functionIndex integer string function functionName ByVal functionIndex As Integer As String string functionName int functionIndex def functionName functionIndex Parameters functionIndex the index of the function for which the information is desired starting at O 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 www yoctopuce com 157 21 High level API Reference module functionValue YModule Retrieves the advertised value of the nth function on the module function f
209. ng general concepts The application uses the DLL to natively control the locally connected module Control by service 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 Virtual Hub 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 virtual hub The end users will have to start the virtual hub before running the project control software itself unless they decide to install the hub as a service deamon in which case the virtual hub starts automatically when the machine starts up The application connects itself to the virtual hub 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 virtual hubs 1 www yoctopuce com EN virtualhub php www yoctopuce com 23 7 Programming general concepts When a virtual hub is used the control application does not need to reside on the same m
210. ng 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 www yoctopuce com 133 21 High level API Reference YAPI InitAPI ylnitAPI Initializes the Yoctopuce programming library explicitly function yInitAPI mode errmsg node js function InitAPI mode errmsg function yInitAPI mode amp errmsg YRETCODE yInitAPI int mode string amp errmsg YRETCODE yInitAPI int mode NSError errmsg function yInitAPI mode integer var errmsg string integer _ v function ylnitAPI ByVal mode As Integer ByRef errmsg As String As Integer int InitAPI int mode ref string errmsg synchronized static int InitAPI int mode def InitAPI mode errmsg None YAPI It is not strictly needed to call yInitAPI as the library is automatically initialized when calling yRegisterHub for the first time When Y_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 Y_DETECT_NONE Y_DE
211. nld function get_functionld function get_functionld string get_functionld NSString functionld function get_functionld As String string get_functionld String get_functionld def get_functionld For example relayl Returns a string that identifies the voltage sensor ex relayl1 On failure throws an exception or returns Y_FUNCTIONID_INVALID www yoctopuce com 207 21 High level API Reference voltage get_hardwareld YVoltage voltage hardwareld Returns the unique hardware identifier of the voltage sensor in the form SERIAL FUNCTIONID function get_hardwareld function get_hardwareld function get_hardwareld string get_hardwareld NSString hardwareld function get_hardwareld As String string get_hardwareld String get_hardwareld def get_hardwareld The unique hardware identifier is composed of the device serial number and of the hardware identifier of the voltage sensor for example RELAYLO1 123456 relayl1 Returns a string that uniquely identifies the voltage sensor ex RELAYLO1 123456 relayl1 On failure throws an exception or returns Y_HARDWAREID_INVALID 208 www yoctopuce com 21 High level API Reference voltage get_highestValue voltage highestValue Returns the maximal value observed function get_highestValue function get_highestValue function get_highestValue double get_highestValu
212. not need to install a dynamic library specific to Yoctopuce everything is in the executable 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 Then for you project to build correctly you need to link with your project the Yoctopuce library and the prerequisite system libraries For Windows yocto static lib e For Mac OS X libyocto static a IOKit framework and CoreFoundation framework For Linux libyocto static a libm libpthread libusb1 0 and libstdc 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 GO 12h SW Bstecic lyoctosstetic lt Wh e aene lm slept iresd lusb estar Integration as a dynamic library 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 wher
213. nough to use a Yocto Volt Here is the skeleton of a Java code snippet to use the Voltage function a occ Get access to your device connected locally on USB for instance YAPT Rega site chil LA Om O i voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel Hot plug is easy just check that the device is online if voltage isOnline Use voltage get_currentValue 1 www yoctopuce com EN libraries php 2 www yoctopuce com EN virtualhub php www yoctopuce com 89 17 Using the Yocto Volt with Java ferences Let us look at these lines in more details YAPI RegisterHub 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 YVoltage FindVoltage The YVoltage FindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel volt
214. ns are done in a perfectly transparent manner The function get_currentValue returns the corrected value while the function get currentRawValue keeps returning the value before the correction Calibration points are simply Raw_value Corrected_value couples Let us look at the impact of the number of calibration points on the corrections 1 point correction The 1 point correction only adds a shift to the measures For example if you provide the calibration point a b all the measured values are corrected by adding to them b a so that when the value read on the sensor is a the voltage1 function returns b o O es 20 T oor lt gt AN amp 5 g C SS 15 O ne O O 10 5 sensor value 5 10 15 20 25 30 Measure correction with 1 calibration point here 5 10 The application is very simple you only need to call the calibrateFromPoints method of the function you wish to correct The following code applies the correction illustrated on the graph above to the first voltage1 function found Note the call to the saveToFlash method of the module hosting the function so that the module does not forget the calibration as soon as it is disconnected Double ValuesBefore 5 Double ValuesAfter 10 YVoltage f YVoltage FirstVoltage f calibrateFromPoints ValuesBefore ValuesAfter f get_module saveToFlash 2 point correction 2 point correction allows you to perform both a shift and a
215. nsichar ze i integer yDeviceSt errmsgBuffer initialization InitAPI 1 errmsg lt 0 then in errmsg www yoctopuce com 121 20 Using with unsupported languages Wanie end forces a device inventory if yapiUpdateDeviceList 1 errmsg lt 0 then begin writeln errmsg Walt end loads all device handles into dataBuffer if yapiGetAllDevices dataBuffer sizeof dataBuffer neededsize errmsg lt 0 then begin writeln errmsg halt end gets device info from each handle for i 0 to neededsize div sizeof integer 1 do begin if apiGetDevicelInfo dataBuffer i devinfos errmsg lt 0 then begin writeln errmsg halt end writeln pansichar devinfos serial tpansichar devinfos productname end end 20 4 Porting the high level library 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 t
216. nt information regarding the use of the Yocto Volt module in real world situations Make sure to read it carefully before going too far into your project if you want to avoid pitfalls 6 1 Fixing While developing your project you can simply let the module hang at the end of its cable Check only that it does not come in contact with any conducting material such as your tools When your project is almost at an end you need to find a way for your modules to stop moving around Examples of assembly on supports The Yocto Volt module contains 2 5mm assembly holes You can use these holes for screws The screw head diameter must not be larger than 4 5mm or they will damage the module circuits Make sure that the lower surface of the module is not in contact with the support We recommend using spacers but other methods are possible Nothing prevents you from fixing the module with a glue gun it will not be good looking but it will hold If your intend to screw your module directly against a conducting part for example a metallic frame insert an isolating layer in between Otherwise you are bound to induce a short circuit there are naked pads under your module Simple packaging tape should be enough for electric insulation www yoctopuce com 15 6 Assembly and connections 6 2 USB power distribution Although USB means Universal Serial BUS USB devices are not physically organized as a flat bus but as a tree using point to po
217. o both parties 122 www yoctopuce com 21 High level API Reference This chapter summarizes the high level API functions to drive your Yocto Volt 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 www yoctopuce com 123 21 High level API Reference 21 1 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 u
218. o find the following modules and this as long as the returned value is not null Below a short example listing the connected modules import com yoctopuce YoctoAPI public class Demo public static void main String args ery ai setup the API to use local VirtualHub YAPI RegisterHub 127 0 0 1 catch YAPT BHxceptilon ex SyS tenm out OE Intl Cannot eontact VarEualHubsony 127 OTOCI ex getLocalizedMessage System out printin Ensure that the VirtualHub application is running System exit 1 System Gvie josiae ini Denna lasa rt i YModule module YModule FirstModule while module null try l System out printin module get_serialNumber module get productName J earen AET Oee e aaa break module module nextModule YAPI FreeAPI 17 4 Error handling 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
219. o use local VirtualHub YAPIMRegvsterbubi la 7 Om Oe Ie iy Pe Cabeha MAP Shc piewonmex i SyS cem out OE Incl Cannot contact Virtua PULTON i277 OTOC ex getLocalizedMessage System out printiin Ensure that the VirtualHub application rS running System exit 1 System out printlin usage demo serial or logical name ON OFF YModule module if args length 0 module YModule FirstModule if module null System out println No module connected check USB cable System exit 1 else module YModule FindModule args 0 use serial or logical name EEy 1 PE arose lence sl if args 1 equalsIgnoreCase ON module setBeacon YModule BRACON ON else www yoctopuce com 91 17 Using the Yocto Volt with Java module setBeacon YModule BEACON_ OFF System out printin serial Ve modullesiget sex ilalNumber 7 System out println logical name module get_logicalName System out printin luminosity module get_luminosity if module get_beacon YModule BEACON ON System out printin beacon ONAT else System out printin beacon ONTAN System out printin upTime Wi ae wlohe get Gotima L000 ar eyeyet 6 SySeemOuen pent a MUSE current V o OCE CEE sus Gur rem ens mA y System out printin logs n module get_lastLogs i earan VAR Peorien S System out printin args 1 not connected check identification and USB
220. ocess 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 saveToF lash function only 100000 times in the life of the module Make sure you do not call this function within a loop Listing the modules 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 import lt Foundation Foundation h gt import yocto_api h int Main Yin arge const cher arg NSError Verro autoreleasepool Setup the API to use local USB devices if yRegisterHub usb amp error YAPT SUCCESS NSLog RegisterHub error n error localizedDescription return 1 NSLog Device list n YModule module yFirstModule while module nil NSLog 3 3 module serialNumber module productName module module nextModule return 0 12 3 Error handling 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
221. octo API mode is currently available in PHP and Node JS only 10 5 Error handling 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 e If your cod
222. odule 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 192 www yoctopuce com 21 High level API Reference 21 3 Voltage function interface The Yoctopuce application programming interface allows you to read an instant measure of the sensor as well as the minimal and maximal values observed In order to use the functions described here you should include lt script type text javascript src yocto_voltage js gt lt script gt var yoctolib require yoctolib var YVoltage yoctolib Y Voltage require_once yocto_voltage php include yocto_voltage h import yocto_voltage h uses yocto_voltage yocto_voltage vb yocto_voltage cs import com yoctopuce YoctoAPI YVoltage from yocto_voltage import Global functions yFindVoltage func Retrieves a voltage sensor for a given identifier yFirstVoltage Starts the enumeration of voltage sensors currently accessible YVoltage methods voltage calibrateFromPoints rawValues refValues Configures error correction data points in particular to compensate for a possible perturbation of the measure caused by an enclosure voltage describe Returns a short text that describes the voltage sensor in the form TYPE NAME SERIAL FUNCTIONID v
223. odule is online to handle hot plug if voltage isOnline 1 Actually as soon as Opera implements support for the HTTP Access Control Allow Origin header www yoctopuce com EN libraries php 3 www yoctopuce com EN virtualhub php www yoctopuce com 31 9 Using Yocto Volt with Javascript Use voltage get_currentValue Let us look at these lines in more details yocto_api js and yocto_voltage js These two Javascript includes provide access to functions allowing you to manage Yoctopuce modules yocto api js must always be included yocto voltage js is necessary to manage modules containing a voltage sensor such as Yocto Volt yRegisterHub The yRegisterHub 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 yFindVoltage The yFindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 fu
224. oid Naturally the Java for Android API remains perfectly able to connect itself to a VirtualHub running on another OS 18 2 Getting ready Go to the Yoctopuce web site and download the Java for Android programming library 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 18 3 Compatibility 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 1 www yoctopuce com EN libraries php www yoctopuce com 95 18 Using the Yocto Volt with Android Android 4 x 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 USB host support Naturally not only must your
225. oltage get_advertisedValue Returns the current value of the voltage sensor no more than 6 characters voltage get_currentRawValue Returns the uncalibrated unrounded raw value returned by the sensor voltage get_currentValue Returns the current measured value voltage get_errorMessage Returns the error message of the latest error with the voltage sensor voltage get_errorType Returns the numerical error code of the latest error with the voltage sensor voltage get_friendlyName Returns a global identifier of the voltage sensor in the format MODULE_NAME FUNCTION_NAME voltage get_functionDescriptor Returns a unique identifier of type YF UN_DESCR corresponding to the function voltage get_functionld Returns the hardware identifier of the voltage sensor without reference to the module voltage get_hardwareld Returns the unique hardware identifier of the voltage sensor in the form SERIAL FUNCTIONID www yoctopuce com 193 21 High level API Reference voltage get_highestValue Returns the maximal value observed voltage get_logFrequency Returns the datalogger recording frequency for this function or OFF when measures are not stored in the data logger flash memory voltage get_logicalName Returns the logical name of the voltage sensor voltage get_lowestValue Returns the minimal value observed voltage get_module Gets the YModule objec
226. on get_maxValue function get_maxValue double get_maxValue double maxValue function get_maxValue double function get_maxValue As Double double get_maxValue double get_maxValue def get_maxValue Returns a floating point number corresponding to the largest value observed www yoctopuce com 287 21 High level API Reference measure gt get_minValue YMeasure measure minValue Returns the smallest value observed during the time interval covered by this measure function get_minValue function get_minValue function get_minValue double get_minValue double minValue function get_minValue double v _ function get_minValue As Double double get_minValue double get_minValue def get_minValue Returns a floating point number corresponding to the smallest value observed 288 www yoctopuce com 21 High level API Reference measure get_startTimeUTC YMeasure measure gt startTimeUTC Returns the start time of the measure relative to the Jan 1 1970 UTC Unix timestamp function get_startTimeUTC function get_startTimeUTC function get_startTimeUTC double get_startTimeUTC double startTimeUTC function get_startTimeUTC double function get_startTimeUTC As Double double get_startTimeUTC double get_startTimeUTC def get_startTimeUTC When the recording rate is higher then 1 sample per second t
227. on get_recording cpp _ Y_RECORDING_enum get_recording Y_RECORDING_enum recording pas_ function get_recording Integer __vb__ function get_recording As Integer int get_recording int get_recording def get_recording Y DataLogger target get_recording Returns either Y_RECORDING_OFF or Y_RECORDING_ON according to the current activation state of the data logger On failure throws an exception or returns Y_RECORDING_INVALID 256 www yoctopuce com 21 High level API Reference datalogger get_timeUTC datalogger timeUTC Returns the Unix timestamp for current UTC time if known function get_timeUTC function get_timeUTC function get_timeUTC s64 get_timeUTC s64 timeUTC function get_timeUTC int64 function get_timeUTC As Long long get_timeUTC long get_timeUTC def get_timeUTC YDataLogger target get_timeUTC Returns an integer corresponding to the Unix timestamp for current UTC time if known On failure throws an exception or returns Y_TIMEUTC_INVALID YDataLogger www yoctopuce com 257 21 High level API Reference datalogger get_userData YDataLogger datalogger userData Returns the value of the userData attribute as previously stored using method set_userData function get_userData function get_userData function get_userData void get_userData void userData function get_userDa
228. on of voltage sensors started using yFirstVoltage voltage registerTimedReportCallback callback Registers the callback function that is invoked on every periodic timed notification voltage registerValueCallback callback Registers the callback function that is invoked on every change of advertised value voltage set_highestValue newval Changes the recorded maximal value observed voltage set_logFrequency newval Changes the datalogger recording frequency for this function voltage set_logicalName newval Changes the logical name of the voltage sensor 194 www yoctopuce com 21 High level API Reference voltage set_lowestValue newval Changes the recorded minimal value observed voltage set_reportFrequency newval Changes the timed value notification frequency for this function voltage set_resolution newval Changes the resolution of the measured values voltage set_userData data Stores a user context provided as argument in the userData attribute of the function voltage wait_async callback context Waits for all pending asynchronous commands on the module to complete and invoke the user provided callback function www yoctopuce com 195 21 High level API Reference YVoltage FindVoltage YVoltage yFindVoltage Retrieves a voltage sensor for a given identifier function yFindVoltage func node js function FindVoltage func function yFindVoltage func YVoltage yFindVol
229. on yFirstVoltage As YVoltage YVoltage FirstVoltage YVoltage FirstVoltage def FirstVoltage Use the method YVoltage nextVoltage to iterate on next voltage sensors YVoltage Returns a pointer to a YVoltage object corresponding to the first voltage sensor currently online or a null pointer if there are none www yoctopuce com 197 21 High level API Reference voltage calibrateFromPoints YVoltage Configures error correction data points in particular to compensate for a possible perturbation of the measure caused by an enclosure function calibrateFromPoints rawValues refValues function calibrateFromPoints rawValues refValues function calibrateFromPoints rawValues refValues int calibrateFromPoints vector lt double gt rawValues vector lt double gt refValues int calibrateFromPoints NSMutableArray rawValues NSMutableArray refValues function calibrateFromPoints rawValues TDoubleArray refValues TDoubleArray LongInt procedure calibrateFromPoints int calibrateFromPoints List lt double gt rawValues List lt double gt refValues int calibrateFromPoints ArrayList lt Double gt rawValues ArrayList lt Double gt refValues def calibrateFromPoints rawValues refValues Y Voltage target calibrateFromPoints rawValues refValues It is possible to configure up to five correction points Correction points must be provided in ascending order and be in the ran
230. 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 www yoctopuce com 93 17 Using the Yocto Volt with Java 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 94 www yoctopuce com 18 Using the Yocto Volt with Android 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 18 1 Native access and VirtualHub 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 Andr
231. ontrolled 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 usr bin python coding utf 8 impo h TOS SVS from yocto api import def usage sys exit usage demo lt serial or logical name gt ON OFF errmsg YRefParam if YAPI RegisterHub usb errmsg YAPI SUCCESS sys exit RegisterHub error str errmsg if len sys argv lt 2 usage m YModule FindModule sys argv 1 use serial or logical name if m isOnline ie lensys acg 2 if sys argv 2 upper ON m set_beacon YModule BEACON ON if sys argv 2 upper OFF m set_beacon YModule BEACON OFF print Wisierenecil m get_serialNumber print logical name m get_logicalName print luminosity Ut stalmiger mino siie O Lemigeribedeconi m YModule BEACON_ON print beacon ON elses print beacon OFE www yoctopuce com 85 16 Using the Yocto Volt with Python print upTime US estul mageteuplamer 7 O00 tu seeu prine USB iecumrentc resi Mm igermusb urrent Ea mAN print logs n m get_lastLogs elses pene syseangvl net connected check adentitalcation and USB cable 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 xx
232. or a longer period in order to reduce network trafic 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 180 www yoctopuce com 21 High level API Reference module load_async YModule Preloads the module cache with a specified validity duration asynchronous version function load_async msValidity callback context 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 trafic 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
233. or logical name gt lt new logical name gt Systeme sxe ls YModule m String newname m YModule FindModule args 0 use serial or logical name cry 4 newname args 1 if YAPI CheckLogicalName newname System out printin Invalid name newname System exire 1i m set_logicalName newname m saveToFlash do not forget this System oue prantin Module serial migel serialNumbex 92 www yoctopuce com 17 Using the Yocto Volt with Java System out println name m get_logicalName Gkenerele MBI ispwereyoneieyn ez System out printlin Module args 0 not connected check identification and USB cable System out printin ex getMessage System exit 1 YAPI FreeAPI 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 Listing the modules 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 t
234. ou 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 10 1 Getting ready Go to the Yoctopuce web site and download the following items The PHP programming library e The VirtualHub software for Windows Mac OS X or Linux depending on your OS 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 10 2 Control of the Voltage function A few lines of code are enough to use a Yocto Volt Here is the skeleton of a PHP code snipplet to use the Voltage function inelude Yyocro jap sphp include yocto_voltage php 1A couple of free PHP servers easyPHP for Windows MAMP for Mac OS X www yoctopuce com EN libraries php 3 www yoctopuce com EN virtualhub php www yoctopuce com 39 10 Using Yocto Volt with PHP Get access to your device through the VirtualHub running locally yRegisterHub http 127 0 0 1 4444 Serrmsg Svoltage yFindVoltage VOLTAGE1 123456 voltagel Check that the module is online to handle hot plug if voltage gt isOnline M Use VOU bdg eget Curren tValiie i e Let s look at these lines in more details yocto_api php and yocto_voltage php These two PHP includes provide
235. 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 Listing the modules 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 lt HTML gt lt HEAD gt lt TITLE gt Modules inventory lt TITLE gt lt SCRIPT type text javascript sre yocto_api js gt lt SCRIPI gt lt SCRIPT language javascriptl 5 type text JavaScript gt aia Use explicit error handling rather than exceptions www yoctopuce com 35 9 Using Yocto Volt with Javascript yDisableExceptions Setup the API to use the VirtualHub on local machine if yRegisterHub http 127 0 0 1 4444 YAPI SUCCESS alent Weannot Contact Vailmtialhibimon 127 0m0 function refresh yUpdateDeviceList var htmlcode var module yFirstModule while module htmlcode module get_serialNumber Pat mMmocdulerqer produc ENa meN A DE module module nextModule document getElementById list innerHTML htmlcode setTimeout ref
236. ples Doc GettingStarted Yocto Volt 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 usr bin python coding utf 8 import os sys from yocto api import from yocto voltage import def usage 84 www yoctopuce com 16 Using the Yocto Volt with Python scriptname os path basename sys argv 0 print Usage print scriptname lt serial_ number gt print scriptname lt logical_name gt print scriptname any sys exit def die msg SVs coche luee Venes WSS eile errmsg YRefParam if len sys argv lt 2 usage target sys argv 1 Setup the API to use local USB devices if YAPI RegisterHub usb errmsg YAPI SUCCESS Sys exit init error errmsg value if target any retreive any voltage sensor sensor YVoltage FirstVoltage if sensor is None die No module connected m sensor get module target m get_serialNumber sensorDC YVoltage FindVoltage target sensorAC YVoltage FindVoltage target if not sensorDC isOnline die device T voltagel voltage2 not connected while True joreakimne VSee asiaAiew Ie 7 wea View ING Circle tte wiccje A aN sensorDC get currentValue sensorAC get currentValue YAPI Sleep 1000 16 4 Control of the module part Each module can be c
237. procedure yRegisterLogFunction ByVal logfun As yLogFunc cs void RegisterLogFunction yLogFunc logfun java _ void RegisterLogFunction LogCallback logfun def RegisterLogFunction logfun This callback will be called each time the API have something to say Quite usefull to debug the API Parameters logfun a procedure taking a string parameter or nul 1 140 www yoctopuce com 21 High level API Reference YAPI SelectArchitecture YAPI ySelectArchitecture Select the architecture or the library to be loaded to access to USB def 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 1386 x86 64 32570 TO4DIET Returns nothing On failure throws an exception www yoctopuce com 141 21 High level API Reference YAPI SetDelegate YAPI ySetDelegate Objective C only Register an object that must follow the procol YDeviceHotPlug void ySetDelegate id object The methodes yDeviceArrival and yDeviceRemoval will be invoked while
238. r def 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_FUNCTIONDESCRIPTOR_INVALID 250 www yoctopuce com 21 High level API Reference datalogger get_functionld YDataLogger datalogger functionld Returns the hardware identifier of the data logger without reference to the module function get_functionld function get_functionld function get_functionld string get_functionld NSString functionld function get_functionld As String string get_functionld String get_functionld def get_functionld For example relayl Returns a string that identifies the data logger ex relay1 On failure throws an exception or returns Y_FUNCTIONID_INVALID www yoctopuce com 251 21 High level API Reference datalogger get_hardwareld YDataLogger datalogger hardwareld Returns the unique hardware identifier of the data logger in the form SERIAL FUNCTIONID function get_hardwareld function get_hardwareld function get_hardwareld string get_hardwareld NSString hardwareld function get_hardwareld As String string get_hardwareld String get_hardwareld def get_hardwareld The unique hardware identifier is composed of
239. r code www yoctopuce com 185 21 High level API Reference module set_beacon YModule module setBeacon Turns on or off the module localization beacon function set_beacon newval function set_beacon newval function set_beacon newval int set_beacon Y_BEACON_enum newval int setBeacon Y_BEACON_enum newval function set_beacon newval Integer integer v function set_beacon ByVal newval As Integer As Integer int set_beacon int newval int set_beacon int newval def set_beacon newval YModule target set_beacon newval Parameters newval either Y_BEACON_OFF or Y_BEACON_ON Returns YAPI SUCCESS if the call succeeds On failure throws an exception or returns a negative error code 186 www yoctopuce com 21 High level API Reference module set_logicalName YModule module gt setLogicalName Changes the logical name of the module function set_logicalName newval function set_logicalName newval function set_logicalName newval int set_logicalName const string amp newval int setLogicalName NSString newval function set_logicalName newval string integer function set_logicalName ByVal newval As String As Integer int set_logicalName string newval int set_logicalName String newval def set_logicalName newval YModule target set_logicalName newval You can use yCheckLogicalName prior to this call to make sure that your parame
240. r Y_AUTOSTART_ON according to the default activation state of the data logger on power up On failure throws an exception or returns Y_AUTOSTART_INVALID www yoctopuce com 243 21 High level API Reference datalogger get_currentRunIndex YDataLogger datalogger currentRunIndex Returns the current run number corresponding to the number of times the module was powered on with the dataLogger enabled at some point function get_currentRunIndex function get_currentRunIndex function get_currentRunIndex int get_currentRunindex int currentRunIndex pas function get_currentRunIndex Longint ve _ function get_currentRunIndex As Integer int get_currentRunIndex int get_currentRunIndex def get_currentRunIndex YDataLogger target get_currentRunindex Returns an integer corresponding to the current run number corresponding to the number of times the module was powered on with the dataLogger enabled at some point On failure throws an exception or returns Y_CURRENTRUNINDEX_INVALID 244 www yoctopuce com 21 High level API Reference datalogger get_dataSets YDataLogger datalogger dataSets Returns a list of YDataSet objects that can be used to retrieve all measures stored by the data logger function get_dataSets function get_dataSets function get_dataSets vector lt YDataSet gt get_dataSets NSMutableArray dataSets function ge
241. r message of the latest error with this module object function get_errorMessage function get_errorMessage function get_errorMessage string get_errorMessage NSString errorMessage function get_errorMessage string function get_errorMessage As String string get_errorMessage String get_errorMessage def get_errorMessage This method is mostly useful when using the Yoctopuce library with exceptions disabled YModule Returns a string corresponding to the latest error message that occured while using this module object 160 www yoctopuce com 21 High level API Reference module get_errorType YModule module errorType Returns the numerical error code of the latest error with this module object function get_errorType function get_errorType function get_errorType YRETCODE get_errorType function get_errorType YRETCODE function get_errorType As YRETCODE YRETCODE get_errorType int get_errorType def 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 occured while using this module object www yoctopuce com 161 21 High level API Reference module gt get_firmwareRelease YModule module gt firmwareRelease Returns the version of the firmware embedded in the module function get_firmwareRelease funct
242. r returns an empty array www yoctopuce com 277 21 High level API Reference dataset get_progress YDataSet dataset progress Returns the progress of the downloads of the measures from the data logger on a scale from 0 to 100 function get_progress function get_progress function get_progress cpp int get_progress int progress pas_ function get_progress LongInt v function get_progress As Integer lt s int get_progress java int get_progress def get_progress When the object is instanciated by get_dataSet the progress is zero Each time loadMore is invoked the progress is updated to reach the value 100 only once all measures have been loaded Returns an integer in the range 0 to 100 percentage of completion 278 www yoctopuce com 21 High level API Reference dataset get_startTimeUTC YDataSet dataset startTimeUTC Returns the start time of the dataset relative to the Jan 1 1970 function get_startTimeUTC function get_startTimeUTC function get_startTimeUTC s64 get_startTimeUTC s64 startTimeUTC function get_startTimeUTC int64 function get_startTimeUTC As Long long get_startTimeUTC long get_startTimeUTC def get_startTimeUTC When the YDataSet is created the start time is the value passed in parameter to the get_dataSet function After the very first call to LoadMore the start time
243. reated the end time is the value passed in parameter to the get_dataSet function After the very first call to LoadMore the end time is updated to reflect the timestamp of the last measure actually found in the dataLogger within the specified range Returns an unsigned number corresponding to the number of seconds between the Jan 1 1970 and the end of this data set i e Unix time representation of the absolute time www yoctopuce com 273 21 High level API Reference dataset get_functionld YDataSet dataset functionld Returns the hardware identifier of the function that performed the measure without reference to the module function get_functionld function get_functionld function get_functionld string get_functionld NSString functionld function get_functionld string v function get_functionld As String string get_functionld String get_functionld def get_functionld For example temperaturel Returns a string that identifies the function ex temperaturel 274 www yoctopuce com 21 High level API Reference dataset get_hardwareld YDataSet dataset hardwareld Returns the unique hardware identifier of the function who performed the measures in the form SERIAL FUNCTIONID function get_hardwareld function get_hardwareld function get_hardwareld string get_hardwareld NSString hardwareld function get_hardwareld
244. reference to receive any error message Returns YAP I SUCCESS when the call succeeds On failure throws an exception or returns a negative error code www yoctopuce com 135 21 High level API Reference YAPI RegisterDeviceArrivalCallback YAPI yRegisterDeviceArrivalCallback Register a callback function to be called each time a device is pluged function yRegisterDeviceArrivalCallback arrivalCallback nodejs function RegisterDeviceArrivalCallback arrivalCallback function yRegisterDeviceArrivalCallback arrivalCallback void yRegisterDeviceArrivalCallback yDeviceUpdateCallback arrivalCallback void yRegisterDeviceArrivalCallback yDeviceUpdateCallback arrivalCallback procedure yRegisterDeviceArrivalCallback arrivalCallback yDeviceUpdateFunc procedure yRegisterDeviceArrivalCallback ByVal arrivalCallback As yDeviceUpdateFunc void RegisterDeviceArrivalCallback yDeviceUpdateFunc arrivalCallback synchronized static void RegisterDeviceArrivalCallback DeviceArrivalCallback arrivalCallback def RegisterDeviceArrivalCallback arrivalCallback This callback will be invoked while yUpdat eDeviceList is running You will have to call this function on a regular basis Parameters arrivalCallback a procedure taking a YModule parameter or null 136 www yoctopuce com 21 High level API Reference YAPI RegisterDeviceRemovalCallback YAPI yRegisterDeviceRemovalCallback Register a c
245. resh 500 gt lt 4 0 Rae ee lt HEAD gt lt BODY onload refresh gt lt H1l gt Device list lt H1 gt lt tt gt lt span id list gt lt span gt lt tt gt lt BODY gt lt HTML gt 9 4 Error handling 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
246. rgs YModule m string errmsg string newname if args Length 2 usage if YAPI RegisterHub usb ref errmsg YAPI SUCCESS Console WriteLine RegisterHub error errmsg Environment Exit 0 m YModule FindModule args 0 use serial or logical name if m isOnline newname args 1 if YAPI CheckLogicalName newname Console WriteLine Invalid name newname Environment Exit 0 m set_logicalName newname m saveToPlash do not forget this Console Write Module serial m get_serialNumber Console WriteLine name m get_logicalName elgg Console Write not connected check identification and USB cable www yoctopuce com 73 14 Using Yocto Volt with C 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 Listing the modules 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 functio
247. ring integer function yRegisterHub ByVal url As String ByRef errmsg As String As Integer int RegisterHub string url ref string errmsg synchronized static int RegisterHub String url def RegisterHub url errmsg None The parameter will determine how the API will work Use the follwing 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 harware 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 keywork 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 ou 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 particu
248. ript you only need a text editor and a web browser to realize your first tests At the time of writing the Javascript library functions with any recent browser except Opera It is likely that Opera will end up working with the Yoctopuce library one of these days but it is not the case right now Javascript is one of those languages which do not allow you to directly access the hardware layers of your computer Therefore you need to run the Yoctopuce TCP IP to USB gateway named VirtualHub on the machine on which your modules are connected 9 1 Getting ready Go to the Yoctopuce web site and download the following items e The Javascript programming library e The VirtualHub software for Windows Mac OS X or Linux depending on your OS 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 9 2 Control of the Voltage function A few lines of code are enough to use a Yocto Volt Here is the skeleton of a JavaScript code snipplet to use the Voltage function lt SCRIPT type text javascript src yocto_apil jjs gt lt SCRIPT gt lt SCRIPT type text javascript src yocto _volitage js gt lt SCRIPT gt Get access to your device through the VirtualHub running locally yRegisterHub http 127 0 0 1 4444 var voltage yFindVoltage VOLTAGE1 123456 voltagel Check that the m
249. riteln off Writeln uptime m Toote Mme GSie mup Time Cliny ILO arise P Writeln USB current g Wak intToStr module get_usbCurrent mA Writeln Logs eye Writeln module get_lastlogs Weiteln gt Writeln r refresh b beacon ON space beacon off end else Writeln Module not connected check identification and USB cable end www yoctopuce com 79 15 Using Yocto Volt with Delphi procedure beacon module Tymodule state integer begin module set_beacon state refresh module end var module TYModule 5 ehar errmsg string begin Setup the API to use local USB devices if yRegisterHubi usb errmsg lt gt YAPT SUCCHSS then begin Write RegisterHub error errmsg exit end module yFindModule serial refresh module mepweas read c i case c of r refresh module b beacon module Y BEACON ON Ds beacon module Y BEACON ORE end Pati se Th end 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 Changing the module settings 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
250. rray of measured values since in some cases it would cause a huge load that could affect the responsiveness of the application Instead this function will return an YDataSet object that can be used to retrieve immediately an overview of the measured data summary and then to load progressively the details when desired Here are the main methods used to retrieve recorded measures dataset sensor get_recordedData 0 0 select the desired time interval dataset loadMore load data from the device progressively dataset get_summary get a single measure summarizing the full time interval dataset get_preview get an array of measures representing a condensed version of the whole set of measures on the selected time interval reduced by a factor of approx 200 dataset get_measures get an array with all detailled measures that grows while loadMo re is being called repeteadly PON gt a Measures are instances of YMeasure They store simultaneously the minimal average and maximal value at a given time that you can retrieve using methods get_minValue get_averageValue and get_maxValue respectively Here is a small example that uses the functions above We will retrieve all measures without time limit parabe fdardce ni sens ora Gelemsne Corcded Dai Oj mO i First call to loadMore loads the summary preview dataset loadMore YMeasure summary dataset get_summary string timeFmt dd MMM yyyy hh mm ss f
251. s Naturally the libraries function in a strictly identical manner if you integrate them in an application with a graphical interface 13 3 Control of the Voltage function A few lines of code are enough to use a Yocto Volt Here is the skeleton of a Visual Basic code snipplet to use the Voltage function eee Dim errmsg As String errmsg Dim voltage As YVoltage REM Get access to your device connected locally on USB for instance yRegisterHub usb errmsg voltage yFindVoltage VOLTAGE1 123456 voltagel REM Hot plug 2s easy Just Cheek that the device as online If voltage isOnline Then REM Use voltage get curren Vauc Mi 2 End If Let s look at these lines in more details yRegisterHub The yRegisterHub 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 yFindVoltage The yFindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 fu
252. s function CheckLogicalName name function yCheckLogicalName name bool yCheckLogicalName const string amp name BOOL yCheckLogicalName NSSiring name function yCheckLogicalName name string boolean function yCheckLogicalName ByVal name As String As Boolean bool CheckLogicalName string name boolean CheckLogicalName String name def CheckLogicalName name A valid logical name has a maximum of 19 characters allamongA 2Z 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 126 www yoctopuce com 21 High level API Reference YAPI DisableExceptions YAPI yDisableExceptions Disables the use of exceptions to report runtime errors function yDisableExceptions function DisableExceptions function yDisableExceptions void yDisableExceptions void yDisableExceptions procedure yDisableExceptions procedure yDisableExceptions void DisableExceptions def 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 www yoctopuce com 127 21 High level API Reference YAPI EnableExceptions YAPI yEnableExceptions Re enables the use of exceptions for runtime error handling fun
253. s 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 e If your code catches the exception and handles it everything goes well e If your program is running in debug mode you can relatively easily determine where the
254. s Y_PERSISTENTSETTINGS_INVALID 168 www yoctopuce com 21 High level API Reference module gt get_productld module gt productld Returns the USB device identifier of the module function get_productld function get_productld function get_productld int get_productld int productld function get_productld LongInt function get_productld As Integer int get_productld int get_productld def get_productld YModule target get_productld Returns an integer corresponding to the USB device identifier of the module On failure throws an exception or returns Y_PRODUCTID_INVALID YModule www yoctopuce com 169 21 High level API Reference module get_productName YModule module productName Returns the commercial name of the module as set by the factory function get_productName function get_productName function get_productName string get_productName NSString productName function get_productName string function get_productName As String string get_productName String get_productName def get_productName 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 Y_PRODUCTNAME_INVALID 170 www yoctopuce com 21 High level API Reference module get_productRelease module gt productRelease
255. s access to the functions allowing you to manage Yoctopuce modules yocto_api php must always be included yocto voltage php is necessary to manage modules containing a voltage sensor such as Yocto Volt yRegisterHub The yRegisterHub 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 yFindVoltage The yFindVoltage function allows you to find a voltage sensor 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 Volt module with serial number VOLTAGE1 123456 which you have named MyModule and for which you have given the voltage1 function the name MyFunction The following five calls are strictly equivalent as long as MyFunction is defined only once Svoltage yFindVoltage VOLTAGE1 123456 voltagel Svoltage yFindVoltage VOLTAGE1 123456 MyFunction Svoltage yFindVoltage MyModule voltagel Svoltage yFindVoltage MyModule MyFunction Svoltage yFindVoltage MyFunction yFindVoltage returns an object which you can then use at will to control th
256. s content function download pathname function download pathname function download pathname string download string pathname NSData download NSString pathname function download pathname string TByteArray function download As Byte def download pathname 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 an empty content 154 www yoctopuce com 21 High level API Reference module gt functionCount YModule Returns the number of functions beside the module interface available on the module function functionCount function functionCount function functionCount int functionCount int functionCount function functionCount integer function functionCount As Integer int functionCount def functionCount Returns the number of functions on the module On failure throws an exception or returns a negative error code www yoctopuce com 155 21 High level API Reference module functionld YModule Retrieves the hardware identifier of the nth function on the module function functionld functionIndex function functionld functionIndex function functionld functionIndex string functionld int functionIndex NSString functionld int functionIndex function functionld functionIndex integer stri
257. s not Nothing Belowa short example listing the connected modules Module Modulel Sub Main Dim M As ymodule Dim errmsg As String REM Setup the API to use local USB devices If yRegisterHub usb errmsg lt gt YAPI_ SUCCESS Then Console WriteLine RegisterHub error errmsg End End if Console WriteLine Device list M yFirstModule While M IsNot Nothing ConsoverWrittehine Migee serlallNumbex 1 Moget productNamei 7 i M M nextModule www yoctopuce com 67 13 Using Yocto Volt with Visual Basic NET End While End Sub End Module 13 5 Error handling 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
258. sed to retrieve an object that provides interaction with the module In order to use the functions described here you should include lt script type text javascript src yocto_api js gt lt script gt var yoctolib require yoctolib var YAPI yoctolib YAPI var YModule yoctolib YModule require_once yocto_api php include yocto_api h import yocto_api h uses yocto_api yocto_api vb yocto_api cs import com yoctopuce YoctoAPI YModule from yocto_api import Global functions yCheckLogicalName name Checks if a given string is valid as logical name for a module or a function yDisableExceptions Disables the use of exceptions to report runtime errors yEnableExceptions Re enables the use of exceptions for runtime error handling yEnableUSBHost osContext This function is used only on Android yFreeAPI Frees dynamically allocated memory blocks used by the Yoctopuce library yGetAP Version Returns the version identifier for the Yoctopuce library in use yGetTickCount Returns the current value of a monotone millisecond based time counter yHandleEvents errmsg Maintains the device to library communication channel ylnitAPI mode errmsg Initializes the Yoctopuce programming library explicitly yPreregisterHub url errmsg Fault tolerant alternative to RegisterHub yRegisterDeviceArrivalCallback arrivalCallback Register a callback function to be called each time a device is pluged
259. seesesneeseseeseesecseeeesueseeseesceneeneaneenees 123 211 General TUNCHOMS aE EES EEE P iia EA EE E E E E 124 21 2 Module control interface oo cccccccccesssesccceeecceeeecceeeeeessesececeeceeeeeesseeeeesaseaeeeeeeeeeeeeseeeeeaaees 148 21 3 Voltage function interface ooo cece eeeeeeeeeeeeeeeeeeeeee tena anenesaaeeeeenaneneesaaeceenaneceensneeeeneneeees 193 21 4 DataLogger function interface ooo cece eee eee eee eeee eee eeeee settee eeeeeaaeeeseaaeeeeeeaeeeeeeeeeeseneeeees 236 21 5 Recorded data sequence 0 eee ceceescceeeseeceeteeeeeeneneeeeseseeeeseaeseseeaneneaaaeeneanenecnneneenineeees 271 AUB MGASUPCO VAIUS aeeiiaii aiana ia aaea shsattecddzesdednedacdeauantigeieidicegssietsevescasheed 284 22 Troubleshooting oon ceccceeceeesesseeseesesseeneseeseesecseesceeeneneeseeneenesneseeseeseenesneeeenteseenees 291 221 E TANOD ETAK USB EEE hatte aint te ee een len tee 291 22 2 ARM Platiorms HF and EL drase a eaaa i Erai Eha 292 23 VAP ACU NS UNS e ere eaa aeaea a inl ced riian 293 BIUSp rift sienna inate debs Sie a aoa eae ate 295 1 Introduction The Yocto Volt module is a 50x20mm module which allows you to measure by USB a voltage difference a tool commonly called voltmeter The Yocto Volt is able to measure direct voltages as well as alternating voltages It has an accuracy of 0 01V 0 5 when measuring direct current and of 0 1V 3 when measuring alternating current An important characteristic of this device is its electrical
260. sion 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 www yoctopuce com 221 21 High level API Reference voltage load YVoltage Preloads the voltage sensor cache with a specified validity duration is__ function load msValidity node js function load msValidity php function load msValidity YRETCODE load int msValidity YRETCODE load int msValidity function load msValidity integer YRETCODE function load ByVal msValidity As Integer As YRETCODE YRETCODE load int msValidity int load long msValidity def 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 trafic for instance Parameters msValidity an integer corresponding to the validity attributed to the loaded function parameters in milliseconds Returns YAPI_SUCCESS when the call suc
261. ssis 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 waiting loop managing callbacks while true module arrival departure callback YAP UpdateDevicelist ref errmsg non active waiting time managing other callbacks VAP I Sileep S00 ae nerro y 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 Detecting a modification in the value of a sensor The Yoctopuce API also provides a callback system allowing you to be notified automatically with the value of any sensor either when the value has changed in a significant way or periodically a
262. st solution does not work with some versions of Internet Explorer in particular IE 9 on Windows 7 which is not able to open network connections when working on a local file In order to use Internet Explorer you should load the example from a web server No such problem exists with Chrome Firefox or Safari 4 if you do not have a text editor use Notepad rather than Microsoft Word 32 www yoctopuce com 9 Using Yocto Volt with Javascript If your Yocto Volt 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 Volt is connected and where you run the VirtualHub lt HTML gt lt HEAD gt lt TITLE gt Hello World lt TITLE gt lt SCRIPT type text javascript src yocto_api js gt lt SCRIPI gt lt SCRIPT type text javascript sre yocto_voltage js gt lt SCRIPT gt lt SCRIPT language javascriptl1 5 type text JavaScript gt 2S Setup the API to use the VirtualHub on local machine if yRegisterHub http 127 0 0 1 4444 YAPI SUCCESS ales ti MCannor Contacti Mir tual HUG on 2700 function refresh yar sensor sensorAC sensorDC yar Serial document gethillementByldi s rrall ivalue qe Serene Ytj y or use any connected module suitable for the demo sensor yFirstVoltage if sensor serial sensor module get_serialNumber document getElementBylId serial value serial
263. stalling any specific system driver as they leverage the standard HID driver provided with every operating system Windows versions currently supported are Windows XP Windows 2003 Windows Vista and Windows 7 Both 32 bit and 64 bit versions are supported Yoctopuce is frequently testing its modules on Windows XP and Windows 7 Mac OS X versions currently supported are 10 6 Snow Leopard Mac OS X 10 7 Lion and 10 8 Mountain Lion Yoctopuce is frequently testing its modules on Mac OS X 10 6 and 10 7 Linux kernels currently supported are the 2 6 branch and the 3 0 branch Other versions of the Linux kernel and even other UNIX variants are very likely to work as well as Linux support is implemented through the standard libusb API Yoctopuce is frequently testing its modules on Linux kernel 2 6 Android versions currently supported are Android 3 1 and later Moreover it is necessary for the tablet or phone to support the Host USB mode Yoctopuce is frequently testing its modules on Android 4 x on a Nexus 7 and a Samsung Galaxy S3 with the Java for Android library A USB cable type A micro B USB connectors exist in three sizes the standard size that you probably use to connect your printer the very common mini size to connect small devices and finally the micro size often used to connect mobile phones as long as they do not exhibit an apple logo All USB modules manufactured by Yoctopuce use micro size connectors ATLL
264. sual Studio Express 2010 but the process is similar for other versions Start by creating your project Then on the So ution 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 1 http www microsoft com visualstudio en us products 2010 editions visual basic express www yoctopuce com EN libraries php 3 The sources of this DLL are available in the C API www yoctopuce com 63 13 Using Yocto Volt with Visual Basic NET Then add in the same manner the yapi d11 DLL located in the Sources d11 directory 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 application
265. synchronized static void FreeAPI def FreeAPI It is generally not required to call this function unless you want to free all dynamically allocated memory blocks in order to track a memory leak for instance You should not call any other library function after calling yF reeAPI or your program will crash 130 www yoctopuce com 21 High level API Reference YAPI GetAPIVersion yGetAPIVersion Returns the version identifier for the Yoctopuce library in use function yGetAPIVersion function GetAPIVersion function yGetAPIVersion string yGetAPIVersion NSString yGetAP IVersion function yGetAPIVersion string function yGetAPIVersion As String String GetAPIVersion String GetAPIVersion def GetAP IVersion YAPI 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 www yoctopuce com 131 21 High level API Refer
266. t a preset frequency The code necessary to do so is rather similar to the code used to detect when a new module has been connected This technique is useful in particular if you want to detect very quick value changes within a few milliseconds as it is much more efficient than reading repeatedly the sensor value and therefore gives better performances Calliback invocation To enable a better control value change callbacks are only called when the YAPI Sleep and YAPI HandleEvents functions are running Therefore you must call one of these functions at a regular interval either from a timer or from a parallel thread while true inactive waiting loop allowing you to trigger value change callbacks YAPI Sleep 500 ref errmsg In programming environments where only the interface thread is allowed to interact with the user it is often appropriate to call YAPI HandleEvents from this thread 108 www yoctopuce com 19 Advanced programming The value change callback This type of callback is called when a voltage sensor changes in a significant way It takes as parameter the relevant function and the new value as a character string static void valueChangeCallback YVoltage fct string value Console Writehinel fel geL handwaneid value In most programming languages callbacks are global procedures not methods If you wish for the callback to call a method of an object
267. t br gt else printf lt input type radio name beacon value ON gt ON printf lt input type radio name beacon value OFF checked gt OFF lt br gt printf upTime s sec lt br gt intVal S module gt get_upTime 1000 Orsinite tC MUSBmeunsre mite ssmA lt br gt Smodule gt get_usbCurrent printf logs lt br gt lt pre gt s lt pre gt module gt get_lastLogs Be lt input type submit value refresh gt lt FORM gt lt BODY gt lt HTML gt 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 Changing the module settings 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 lt HTML gt lt HEAD gt lt TITLE gt save settings lt T
268. t for the device on which the function is located voltage get_module_async callback context Gets the YModule object for the device on which the function is located asynchronous version voltage get_recordedData startTime endTime Retrieves a DataSet object holding historical data for this sensor for a specified time interval voltage get_reportFrequency Returns the timed value notification frequency or OFF if timed value notifications are disabled for this function voltage get_resolution Returns the resolution of the measured values voltage get_unit Returns the measuring unit for the measured value voltage get_userData Returns the value of the userData attribute as previously stored using method set_userData voltage isOnline Checks if the voltage sensor is currently reachable without raising any error voltage isOnline_async callback context Checks if the voltage sensor is currently reachable without raising any error asynchronous version voltage load msValidity Preloads the voltage sensor cache with a specified validity duration voltage loadCalibrationPoints rawValues refValues Retrieves error correction data points previously entered using the method calibrateFromPoints voltage load_async msValidity callback context Preloads the voltage sensor cache with a specified validity duration asynchronous version voltage nextVoltage Continues the enumerati
269. t newval int set_recording int newval def set_recording newval YDataLogger target set_recording newval Parameters data logger to start stop recording data Returns YAPI_SUCCESS if the call succeeds On failure throws an exception or returns a negative error code YDataLogger newval either Y_RECORDING_OFF or Y_RECORDING_ON according to the activation state of the www yoctopuce com 267 21 High level API Reference datalogger set_timeUTC YDataLogger datalogger setTimeUTC Changes the current UTC time reference used for recorded data function set_timeUTC newval function set_timeUTC newval function set_timeUTC newval int set_timeUTC s64 newval int setTimeUTC s64 newval function set_timeUTC newval int64 integer vo function set_timeUTC ByVal newval As Long As Integer int set_timeUTC long newval int set_timeUTC long newval def set_timeUTC newval Y DataLogger target set_timeUTC newval Parameters newval an integer corresponding to the current UTC time reference used for recorded data Returns YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code 268 www yoctopuce com 21 High level API Reference datalogger set_userData YDataLogger datalogger setUserData Stores a user context provided as argument in the userData attribute of the function function set_userData data
270. t that is passed as is to the callback function Returns nothing www yoctopuce com 283 21 High level API Reference 21 6 Measured value YMeasure objects are used within the API to represent a value measured at a specified time These objects are used in particular in conjunction with the YDataSet class In order to use the functions described here you should include lt script type text javascript src yocto_api js gt lt script gt var yoctolib require yoctolib var YAPI yoctolib YAPI var YModule yoctolib YModule require_once yocto_api php include yocto_api h import yocto_api h uses yocto_api yocto_api vb yocto_api cs import com yoctopuce YoctoAPI YModule from yocto_api import YMeasure methods measure get_averageValue Returns the average value observed during the time interval covered by this measure measure get_endTimeUTC Returns the end time of the measure relative to the Jan 1 1970 UTC Unix timestamp measure get_maxValue Returns the largest value observed during the time interval covered by this measure measure get_minValue Returns the smallest value observed during the time interval covered by this measure measure get_startTimeUTC Returns the start time of the measure relative to the Jan 1 1970 UTC Unix timestamp 284 www yoctopuce com 21 High level API Reference measure get_averageValue YMeasure measure aver
271. t_dataSets TYDataSetArray function get_dataSets As List List lt YDataSet gt get_dataSets ArrayList lt YDataSet gt get_dataSets def get_dataSets YDataLogger target get_dataSets This function only works if the device uses a recent firmware as YDataSet objects are not supported by firmwares older than version 13000 Returns a list of YDataSet object On failure throws an exception or returns an empty list www yoctopuce com 245 21 High level API Reference datalogger get_dataStreams YDataLogger datalogger dataStreams Builds a list of all data streams hold by the data logger legacy method function get_dataStreams v function get_dataStreams v function get_dataStreams amp v cpp int get_dataStreams int dataStreams NSArray v function get_dataStreams v Tlist integer procedure get_dataStreams ByVal v As List int get_dataStreams List lt YDataStream gt v int get_dataStreams ArrayList lt YDataStream gt v def get_dataStreams v The caller must pass by reference an empty array to hold YDataStream objects and the function fills it with objects describing available data sequences This is the old way to retrieve data from the DataLogger For new applications you should rather use get_dataSets method or call directly get_recordedData on the sensor object Parameters v an array of YDataStream objects to be filled in Returns YAPI_SUCCESS if
272. t_usbBandwidth newval function set_usbBandwidth newval function set_usbBandwidth newval int set_usbBandwidth Y_USBBANDWIDTH_enum newval int setUsbBandwidth Y_USBBANDWIDTH_enum newval function set_usbBandwidth newval Integer integer function set_usbBandwidth ByVal newval As Integer As Integer int set_usbBandwidth int newval int set_usbBandwidth int newval def set_usbBandwidth newval YModule target set_usbBandwidth newval You must reboot the module after changing this setting Parameters newval either Y_USBBANDWIDTH_SIMPLE or Y_USBBANDWIDTH_DOUBLE according to the number of USB interfaces used by the module Returns YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code www yoctopuce com 189 21 High level API Reference module set_userData YModule module setUserData Stores a user context provided as argument in the userData attribute of the function function set_userData data function set_userData data function set_userData data void set_userData void data void setUserData void data procedure set_userData data Tobject procedure set_userData ByVal data As Object void set_userData object data void set_userData Object data def 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
273. ta Tobject function get_userData As Object object get_userData Object get_userData def 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 258 www yoctopuce com 21 High level API Reference datalogger isOnline YDataLogger Checks if the data logger is currently reachable without raising any error function isOnline node js function isOnline function isOnline bool isOnline BOOL isOnline function isOnline boolean function isOnline As Boolean bool isOnline boolean isOnline def isOnline If there is a cached value for the data logger 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 data logger Returns true if the data logger can be reached and false otherwise www yoctopuce com 259 21 High level API Reference datalogger isOnline_async YDataLogger Checks if the data logger is currently reachable without raising any error asynchronous version is _ function isOnline_async callback context node js function isOnline_async callback context If there is a cached value for the data logger in cache that has not yet expired the device is considered reachable No exception is raised if ther
274. taSetChanged Override protected void onStop super onStop YAPI FreeAPI private void DisplayModuleInfo TextView field if module null iagshewhaialy ery 4 field TextView findViewById R id serialfield field setText module getSerialNumber field TextView findViewById R id logicalnamefield field setText module getLogicalName field TextView findViewById R id luminosityfield field setText String format Sd module getLuminosity field TextView findViewById R id uptimefield field setText module getUpTime 1000 sec field TextView findViewById R id usbcurrentfield field setText module getUsbCurrent mA Switch sw Switch findViewById R id beaconswitch Log d sviten bedconl module igeusbeacon i sw setChecked module getBeacon YModule BEACON_ON field TextView findViewById R id logs Eveldscelext module get lastlogsi je Cacch VAP TEE Xcepel one e printStackTrace Override public void onItemSelected AdapterView lt gt parent View view int pos long id String hwid parent getItemAtPosition pos toString module YModule FindModule hwid DisplayModuleInfo Override public void onNothingSelected AdapterView lt gt arg0 public void refreshInfo View view DisplayModulelInfo www yoctopuce com 101 18 Using the Yocto Volt w
275. tage const string amp func YVoltage yFindVoltage NSString func function yFindVoltage func string TYVoltage function yFindVoltage ByVal func As String As YVoltage YVoltage FindVoltage string func YVoltage FindVoltage String func def FindVoltage func The identifier can be specified using several formats e FunctionLogicalName e ModuleSerialNumber Functionldentifier e ModuleSerialNumber FunctionLogicalName e ModuleLogicalName Functionldentifier e ModuleLogicalName FunctionLogicalName This function does not require that the voltage sensor is online at the time it is invoked The returned object is nevertheless valid Use the method YVoltage isOnline to test if the voltage sensor is indeed online at a given time In case of ambiguity when looking for a voltage sensor 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 func a string that uniquely characterizes the voltage sensor Returns a YVoltage object allowing you to drive the voltage sensor 196 www yoctopuce com 21 High level API Reference YVoltage FirstVoltage yFirstVoltage Starts the enumeration of voltage sensors currently accessible function yFirstVoltage function FirstVoltage function yFirstVoltage YVoltage yFirstVoltage YVoltage yFirstVoltage function yFirstVoltage TYVoltage functi
276. ted This method does not trigger any USB or TCP transaction and can therefore be used in a debugger Returns a string that describes the voltage sensor ex Relay MyCustomName relayl RELAYLO1 123456 relayl www yoctopuce com 199 21 High level API Reference voltage get_advertisedValue YVoltage voltage advertisedValue Returns the current value of the voltage sensor no more than 6 characters function get_advertisedValue function get_advertisedValue function get_advertisedValue string get_advertisedValue NSString advertisedValue function get_advertisedValue string function get_advertisedValue As String string get_advertisedValue String get_advertisedValue def get_advertisedValue YVoltage target get_advertisedValue Returns a string corresponding to the current value of the voltage sensor no more than 6 characters On failure throws an exception or returns Y_ADVERTISEDVALUE_INVALID 200 www yoctopuce com 21 High level API Reference voltage get_currentRawValue voltage currentRawValue Returns the uncalibrated unrounded raw value returned by the sensor function get_currentRawValue function get_currentRawValue function get_currentRawValue double get_currentRawValue double currentRawValue function get_currentRawValue double function
277. ter is valid Remember to call the saveToF lash 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 www yoctopuce com 187 21 High level API Reference module set_luminosity YModule module setLuminosity Changes the luminosity of the module informative leds function set_luminosity newval function set_luminosity newval function set_luminosity newval int set_luminosity int newval int setLuminosity int newval function set_luminosity newval LongInt integer v function set_luminosity ByVal newval As Integer As Integer int set_luminosity int newval int set_luminosity int newval def set_luminosity newval 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 188 www yoctopuce com 21 High level API Reference module set_usbBandwidth YModule module setUsbBandwidth Changes the number of USB interfaces used by the module function se
278. 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 8 5 Limitations 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 VirtualHub on the concerned machine and use the executables of the command line API with the r option For example if you use YModule inventory 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 YModule r 127 0 0 1 inventory 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 3 http www yoctopuce com EN virtualhub php www yoctopuce com 29 30 www yoctopuce com 9 Using Yocto Volt with Javascript Javascript is probably not the first language that comes to mind to control hardware but its ease of use is a great advantage with Javasc
279. the call succeeds On failure throws an exception or returns a negative error code 246 www yoctopuce com 21 High level API Reference datalogger get_errorMessage YDataLogger datalogger errorMessage Returns the error message of the latest error with the data logger function get_errorMessage function get_errorMessage function get_errorMessage string get_errorMessage NSString errorMessage function get_errorMessage string function get_errorMessage As String string get_errorMessage String get_errorMessage def 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 data logger object www yoctopuce com 247 21 High level API Reference datalogger get_errorType YDataLogger datalogger errorType Returns the numerical error code of the latest error with the data logger function get_errorType function get_errorType function get_errorType YRETCODE get_errorType function get_errorType YRETCODE function get_errorType As YRETCODE YRETCODE get_errorType int get_errorType def 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 occured while using the data logg
280. tised value www yoctopuce com 227 21 High level API Reference voltage set_highestValue voltage setHighestValue Changes the recorded maximal value observed function set_highestValue newval function set_highestValue newval function set_highestValue newval int set_highestValue double newval int setHighestValue double newval function set_highestValue newval double integer v _ function set_highestValue ByVal newval As Double As Integer int set_highestValue double newval int set_highestValue double newval def set_highestValue newval YVoltage target set_highestValue newval Parameters newval a floating point number corresponding to the recorded maximal value observed Returns YAPI_ SUCCESS if the call succeeds On failure throws an exception or returns a negative error code YVoltage 228 www yoctopuce com 21 High level API Reference voltage set_logFrequency voltage setLogFrequency Changes the datalogger recording frequency for this function function set_logFrequency newval function set_logFrequency newval function set_logFrequency newval int set_logFrequency const string amp newval int setLogFrequency NSString newval function set_logFrequency newval string integer function set_logFrequency ByVal newval As String As Integer int set_logFrequency string newval int set_logFrequency String newval def set
281. toOp i YAPI FreeAPI private void DisplayModuleInfo TextView field if module null iste wun s Ery YAPI UpdateDeviceList fixme field TextView findViewById R id logicalnamefield field setText module getLogicalName PC aieic han MAPA Shc pe aonne ie printStackTrace Override public void onItemSelected AdapterView lt gt parent View view int pos long id String hwid parent getItemAtPosition pos toString module YModule FindModule hwid DisplayModuleInfo Override public void onNothingSelected AdapterView lt gt arg0 public void saveName View view if module null ise Whately EditText edit EditText findViewById R id newname String newname edit getText toString try if YAPI CheckLogicalName newname Toast makeText getApplicationContext Invalid name newname Toast LENGTH_ LONG show TAS UEIN module set_logicalName newname module saveToFlash do not forget this edit setText Catch YAPT Exception ex ex printStackTrace DisplayModuleInfo 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 www yoctopuce com 103 18 Using the Yocto Volt with Android the technology employed by the module mi
282. ucceeds On failure throws an exception or returns a negative error code www yoctopuce com 183 21 High level API Reference module gt revertFromFlash YModule Reloads the settings stored in the nonvolatile memory as when the module is powered on 5s function revertFromFlash koasjs function revertFromFlash prp function revertFromFlash cep_ int revertFromFlash int revertFromFlash eas _ function revertFromFlash Longint vo function revertFromFlash As Integer cs _ intrevertFromFlash java int revertFromFlash def revertFromFlash YModule target revertFromFlash Returns YAPI_SUCCESS when the call succeeds On failure throws an exception or returns a negative error code 184 www yoctopuce com 21 High level API Reference module saveToFlash Saves current settings in the nonvolatile memory of the module function saveToFlash function saveToFlash function saveToFlash int saveToFlash int saveToFlash function saveToFlash Longint function saveToFlash As Integer int saveToFlash int saveToFlash def saveToFlash YModule target saveToFlash YModule 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 erro
283. uivalent as long as MyFunction is defined only once voltage YVoltage FindVoltage VOLTAGE1 123456 voltagel1 voltage YVoltage FindVoltage VOLTAGE1 123456 MyFunction voltage YVoltage FindVoltage MyModule voltagel voltage YVoltage FindVoltage MyModule MyFunction voltage YVoltage FindVoltage MyFunction YVoltage FindVoltage returns an object which you can then use at will to control the voltage sensor isOnline The isOnline method of the object returned by YVoltage FindVoltage allows you to know if the corresponding module is present and in working order get_currentValue The get_currentValue method of the object returned by YVoltage FindVoltage allows you to obtain the voltage as measured by the sensor The return value is a number directly representing the value in Volts 98 www yoctopuce com 18 Using the Yocto Volt with Android A real example 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 package com yoctopuce doc_examples impor impor impor impor impor impor impor impor impor r ver rider me er ier er Ge impor impor impor impor am ap tee toy public android app Activity android os Bundle
284. ules through one or more USB hub without external power supply you have no safe guard and you depend entirely on your computer manufacturer attention to provide as much current as possible on the USB ports and to detect overloads before they lead to problems or to hardware damages When modules are not provided enough current they may work erratically and create unpredictable bugs If you want to prevent any risk do not cascade hubs without external power supply and do not connect peripherals requiring more than 100mA behind a bus powered hub In order to help controlling and planning overall power consumption for your project all Yoctopuce modules include a built in current sensor that tells with 5mA precision the consumption of the module on the USB bus 16 www yoctopuce com 7 Programming general concepts The Yoctopuce API was designed to be at the same time simple to use and sufficiently generic for the concepts used to be valid for all the modules in the Yoctopuce range and this in all the available programming languages Therefore when you have understood how to drive your Yocto Volt 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 7 1 Programming paradigm The Yoctopuce API is object oriented However for simplicity s sake only the basics of object programming were used Even if you are not familiar with object progr
285. unctionValue functionIndex function functionValue functionIndex function functionValue functionIndex string functionValue int functionIndex NSString functionValue int functionIndex function functionValue functionIndex integer string function functionValue ByVal functionIndex As Integer As String string functionValue int functionindex def functionValue functionIndex Parameters functionIndex the index of the function for which the information is desired starting at O 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 158 www yoctopuce com 21 High level API Reference module get_beacon module gt beacon Returns the state of the localization beacon function get_beacon function get_beacon function get_beacon Y_BEACON_enum get_beacon Y_BEACON_enum beacon function get_beacon Integer function get_beacon As Integer int get_beacon int get_beacon def get_beacon YModule target get_beacon Returns YModule either Y_BEACON_OFF or Y_BEACON_ON according to the state of the localization beacon On failure throws an exception or returns Y_BEACON_INVALID www yoctopuce com 159 21 High level API Reference module get_errorMessage module errorMessage Returns the erro
286. urns the default activation state of the data logger on power up datalogger get_currentRunIndex Returns the current run number corresponding to the number of times the module was powered on with the dataLogger enabled at some point datalogger get_dataSets Returns a list of YDataSet objects that can be used to retrieve all measures stored by the data logger datalogger get_dataStreams v Builds a list of all data streams hold by the data logger legacy method datalogger get_errorMessage Returns the error message of the latest error with the data logger datalogger get_errorType Returns the numerical error code of the latest error with the data logger datalogger get_friendlyName Returns a global identifier of the data logger in the format MODULE_NAME FUNCT ION_NAME datalogger get_functionDescriptor Returns a unique identifier of type YF UN_DESCR corresponding to the function 236 www yoctopuce com 21 High level API Reference datalogger get_functionld Returns the hardware identifier of the data logger without reference to the module datalogger get_hardwareld Returns the unique hardware identifier of the data logger in the form SERIAL FUNCTIONID datalogger get_logicalName Returns the logical name of the data logger datalogger get_module Gets the YModule object for the device on which the function is located datalogger get_module_async callback context
287. va 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 www yoctopuce com 105 106 www yoctopuce com 19 Advanced programming The preceding chapters have introduced in each available language the basic programming functions which can be used with your Yocto Volt 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 19 1 Event programming 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 modifi
288. veToFlash 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 import lt Foundation Foundation h gt import yocto_api h static void usage const char exe NSLog usage s lt serial gt lt newLogicalName gt n exe exis 1i int neaka Yin argc Const char w ewei NSError error autoreleasepool Setup the API to use local USB devices if yRegisterHub usb amp error YAPT SUCCESS NSLog RegisterHub error error localizedDescription return 1 Litera 2 usage argv 0 NSString serial or name NSString stringWithUTF8String argv 1 YModule module yFindModule serial or name use serial or logical name if module isOnline if argc gt 3 NSString newname NSString stringWithUTF8String argv 2 if yCheckLogicalName newname NSLog Invalid name n newname usage argv 0 module logicalName newname module saveToFlash NSLog Current name n module logicalName oO es n oO NSLog not connected check identification and USB cable n serial or name 60 www yoctopuce com 12 Using Yocto Volt with Objective C 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 pr
289. with Javascript 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 www yoctopuce com 37 38 www yoctopuce com 10 Using Yocto Volt with PHP 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 server preferably locally on you machine If y
290. 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 Listing the modules 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 lt HTML gt lt HEAD gt lt TITLE gt inventory lt TITLE gt lt HEAD gt lt BODY gt lt H1l gt Device list lt H1 gt lt TT gt lt php include yocto_api php yRegisterHub http 127 0 0 1 4444 Smodule yFirstModule while is_ null Smodule printi ss ss lt br gt Smodulle gt get iserralNumber i S module gt get_productName Smodule Smodule gt nextModule 2 gt lt eILS lt BODY gt lt HTML gt www yoctopuce com 43 10 Using Yocto Volt with PHP 10 4 HTTP callback API and NAT filters The PHP library is able to work in a specific mode called HTTP callback Yocto API With this mode you can control Yoctopuce d
291. ws before the load is complete The oldest measures are always loaded first and the most recent measures will be loaded last As a result timestamps are normally sorted in ascending order within the measure table unless there was an unexpected adjustment of the datalogger UTC clock Returns a table of records where each record depicts the measured value for a given time interval On failure throws an exception or returns an empty array 276 www yoctopuce com 21 High level API Reference dataset get_preview YDataSet dataset preview Returns a condensed version of the measures that can retrieved in this YDataSet as a list of YMeasure objects function get_preview function get_preview function get_preview vector lt YMeasure gt get_preview NSMutableArray preview function get_preview TYMeasureArray function get_preview As List List lt YMeasure gt get_preview ArrayList lt YMeasure gt get_preview def get_preview Each item includes the start of a time interval the end of a time interval the minimal value observed during the time interval the average value observed during the time interval the maximal value observed during the time interval This preview is available as soon as loadMore has been called for the first time Returns a table of records where each record depicts the measured values during a time interval On failure throws an exception o
292. x method For more details regarding the used functions refer to the API chapters Changing the module settings 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 usr bin python ip Sot ELRES EISE i import os sys from yocto api import def usage sys exit usage demo lt seriall or logical name gt lt new logical name gt if len sys argv 3 usage errmsg YRefParam if YAPI RegisterHub usb errmsg YAPI SUCCESS SVS exiit GReg eteru error ut eS lena Totem Sop n m YModule FindModule sys argv 1 use serial or logical name if Mm S Om ame newname sys argv 2 if not YAPI CheckLogicalName newname sys exit Invalid name newname m set_logicalName newname m saveToFlash do not forget this print Module serial m get_serialNumber name m get_logicalName else Sys exit
293. y 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 Driving a module The three essential functions of the low level API are the following ine Veo wrmine Ab lint iConne ci Onmrype char erirmsG i int yapiUpdateDeviceList int forceupdate char errmsg int yapiHTTPRequest char device char request char buffer int buffsize int fullsize char errmsg The yapilnitAPI 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 yapiHT TPRequest function sends HTTP requests to the module REST API The device para
294. yRegisterDeviceRemovalCallback removalCallback Register a callback function to be called each time a device is unpluged yRegisterHub url errmsg Setup the Yoctopuce library to use modules connected on a given machine yRegisterHubDiscoveryCallback callback 124 www yoctopuce com 21 High level API Reference Register a callback function to be called each time a network hub or a VirtualHub is detected on the local network yRegisterLogFunction logfun Registers a log callback function ySelectArchitecture arch Select the architecture or the library to be loaded to access to USB ySetDelegate object Objective C only Register an object that must follow the procol YDeviceHotPlug ySetTimeout callback ms_timeout arguments Invoke the specified calloack function after a given timeout ySleep ms_duration errmsg Pauses the execution flow for a specified duration yUnregisterHub url Setup the Yoctopuce library to no more use modules connected on a previously registered machine with RegisterHub yUpdateDeviceList errmsg Triggers a re detection of connected Yoctopuce modules yUpdateDeviceList_async callback context Triggers a re detection of connected Yoctopuce modules www yoctopuce com 125 21 High level API Reference YAPI CheckLogicalName YAPI yCheckLogicalName Checks if a given string is valid as logical name for a module or a function function yCheckLogicalName name node j

User manual

Contents

Download Pdf Manuals

Related Search

Related Contents