Yoctopuce YD128X32 Display User Manual

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

functionCount()

Returns the number of functions (beside the "module" interface) available on the module.

module

functionId(

functionIndex

)

Retrieves the hardware identifier of the nth function on the module.

module

functionName(

functionIndex

)

Retrieves the logical name of the nth function on the module.

module

functionValue(

functionIndex

)

Retrieves the advertised value of the nth function on the module.

module

get_beacon()

Returns the state of the localization beacon.

module

Returns the error message of the latest error with this module object.

module

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

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

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_productId()

Returns the USB device identifier of the module.

module

get_productName()

Returns the commercial name of the module, as set by the factory.

module

get_productRelease()

Returns the 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

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 the module.

module

get_usbCurrent()

Returns the current consumed by the module on the USB bus, in milli-amps.

module

Returns the value of the userData attribute, as previously stored using method set_userData

module

Checks if the module is currently reachable, without raising any error.

module

callback

context

)

Checks if the module is currently reachable, without raising any error.

module

msValidity

)

Preloads the module cache with a specified validity duration.

module

msValidity

callback

context

)

Preloads the module cache with a specified validity duration (asynchronous version).

module

nextModule()

Continues the module enumeration started using yFirstModule() .

module

reboot(

secBeforeReboot

)

Schedules a simple module reboot after the given number of seconds.

module

revertFromFlash()

Reloads the settings stored in the nonvolatile memory, as when the module is powered on.

module

saveToFlash()

Saves current settings in the nonvolatile memory of the module.

module

set_beacon(

newval

)

Turns on or off the module localization beacon.

www.yoctopuce.com

149

21. High-level API Reference

module

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.

module

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

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() yFindModule()

YModule

Allows you to find a module from its serial number or from its logical name.

js nodejs function yFindModule(

func

) function FindModule(

func

) php cpp function yFindModule(

$func

)

YModule* yFindModule( string

func

) m pas vb cs java py

+(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 :

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() yFirstModule()

Starts the enumeration of modules currently accessible.

js function yFirstModule( ) nodejs function FirstModule( ) php cpp m pas function yFirstModule( )

YModule* yFirstModule( )

YModule* yFirstModule( ) function yFirstModule( ): TYModule vb cs java py function yFirstModule( ) As YModule

YModule FirstModule( )

YModule FirstModule( ) def FirstModule( )

Use the method

YModule.nextModule()

to iterate on the next modules.

YModule

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

module

→

describe()

Returns a descriptive text that identifies the module.

js function describe( ) nodejs function describe( ) php function describe( ) cpp m pas vb cs java py 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.

21. High-level API Reference

YModule

Returns :

a string that describes the module

www.yoctopuce.com

153

21. High-level API Reference

module

→

download()

Downloads the specified built-in file and returns a binary buffer with its content.

js function download(

pathname

) nodejs function download(

pathname

) php function download(

$pathname

) cpp m pas vb py cmd 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.

YModule

154 www.yoctopuce.com

21. High-level API Reference

module

→

functionCount()

Returns the number of functions (beside the "module" interface) available on the module.

js function functionCount( ) nodejs function functionCount( ) php function functionCount( ) cpp m pas vb cs py int functionCount( )

-(int) functionCount function functionCount( ): integer function functionCount( ) As Integer int functionCount( ) def functionCount( )

YModule

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

→

functionId()

Retrieves the hardware identifier of the nth function on the module.

js function functionId(

functionIndex

) nodejs function functionId(

functionIndex

) php function functionId(

$functionIndex

) cpp m pas vb cs py string functionId( int

functionIndex

)

-(NSString*) functionId : (int)

functionIndex

function functionId(

functionIndex

: integer): string function functionId( ByVal

functionIndex

As Integer) As String string functionId( int

functionIndex

) def functionId(

functionIndex

)

YModule

Parameters : functionIndex

the index of the function for which the information is desired, starting at 0 for the first function.

Returns :

a string corresponding to the unambiguous hardware identifier of the requested module function

On failure, throws an exception or returns an empty string.

156 www.yoctopuce.com

module

→

functionName()

Retrieves the logical name of the nth function on the module.

js function functionName(

functionIndex

) nodejs function functionName(

functionIndex

) php function functionName(

$functionIndex

) cpp m pas vb cs py 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

)

21. High-level API Reference

YModule

Parameters : functionIndex

the index of the function for which the information is desired, starting at 0 for the first function.

Returns :

a string corresponding to the logical name of the requested module function

On failure, throws an exception or returns an empty string.

www.yoctopuce.com

157

21. High-level API Reference

module

→

functionValue()

Retrieves the advertised value of the nth function on the module.

js function functionValue(

functionIndex

) nodejs function functionValue(

functionIndex

) php function functionValue(

$functionIndex

) cpp m pas vb cs py 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

)

YModule

Parameters : functionIndex

the index of the function for which the information is desired, starting at 0 for the first function.

Returns :

a short string (up to 6 characters) corresponding to the advertised value of the requested module function

On failure, throws an exception or returns an empty string.

158 www.yoctopuce.com

21. High-level API Reference

module

→

get_beacon() module

→

beacon()

Returns the state of the localization beacon.

js nodejs function get_beacon( ) function get_beacon( ) php cpp function get_beacon( )

Y_BEACON_enum get_beacon( ) m pas vb cs

-(Y_BEACON_enum) beacon function get_beacon( ): Integer function get_beacon( ) As Integer int get_beacon( ) java py cmd int get_beacon( ) def get_beacon( )

YModule

target

get_beacon

Returns :

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

YModule

www.yoctopuce.com

159

21. High-level API Reference

module

→

get_errorMessage() module

→

errorMessage()

Returns the error message of the latest error with this module object.

js function get_errorMessage( ) nodejs function get_errorMessage( ) php cpp m pas function get_errorMessage( ) string get_errorMessage( )

-(NSString*) errorMessage function get_errorMessage( ): string vb cs java py 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() module

→

errorType()

Returns the numerical error code of the latest error with this module object.

js nodejs function get_errorType( ) function get_errorType( ) php cpp function get_errorType( )

YRETCODE get_errorType( ) pas vb cs java py 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.

YModule

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

→

get_firmwareRelease() module

→

firmwareRelease()

Returns the version of the firmware embedded in the module.

js function get_firmwareRelease( ) nodejs function get_firmwareRelease( ) php cpp m pas function get_firmwareRelease( ) string get_firmwareRelease( )

-(NSString*) firmwareRelease function get_firmwareRelease( ): string vb cs java py cmd 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_FIRMWARERELEASE_INVALID .

YModule

162 www.yoctopuce.com

21. High-level API Reference

module

→

get_hardwareId() module

→

hardwareId()

YModule

Returns the unique hardware identifier of the module.

js nodejs function get_hardwareId( ) function get_hardwareId( ) php cpp function get_hardwareId( ) string get_hardwareId( ) m vb cs java py

-(NSString*) hardwareId function get_hardwareId( ) As String string get_hardwareId( )

String get_hardwareId( ) def get_hardwareId( )

The unique hardware identifier is made of the device serial number followed by string ".module".

Returns :

a string that uniquely identifies the module

www.yoctopuce.com

163

21. High-level API Reference

module

→

get_icon2d() module

→

icon2d()

Returns the icon of the module.

js function get_icon2d( ) nodejs function get_icon2d( ) php cpp m pas function get_icon2d( ) string get_icon2d( )

-(NSData*) icon2d function get_icon2d( ): TByteArray vb py cmd function get_icon2d( ) As Byte def get_icon2d( )

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.

YModule

164 www.yoctopuce.com

module

→

get_lastLogs() module

→

lastLogs()

Returns a string with last logs of the module.

js nodejs function get_lastLogs( ) function get_lastLogs( ) php cpp function get_lastLogs( ) string get_lastLogs( ) m pas vb cs

-(NSString*) lastLogs function get_lastLogs( ): string function get_lastLogs( ) As String string get_lastLogs( ) java py cmd

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.

21. High-level API Reference

YModule

www.yoctopuce.com

165

21. High-level API Reference

module

→

get_logicalName() module

→

logicalName()

Returns the logical name of the module.

js function get_logicalName( ) nodejs function get_logicalName( ) php cpp m pas function get_logicalName( ) string get_logicalName( )

-(NSString*) logicalName function get_logicalName( ): string vb cs java py cmd 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 .

YModule

166 www.yoctopuce.com

21. High-level API Reference

module

→

get_luminosity() module

→

luminosity()

Returns the luminosity of the module informative leds (from 0 to 100).

js nodejs function get_luminosity( ) function get_luminosity( ) php cpp function get_luminosity( ) int get_luminosity( ) m pas vb cs

-(int) luminosity function get_luminosity( ): LongInt function get_luminosity( ) As Integer int get_luminosity( ) java py cmd 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 .

YModule

www.yoctopuce.com

167

21. High-level API Reference

module

→

get_persistentSettings() module

→

persistentSettings()

Returns the current state of persistent module settings.

js function get_persistentSettings( ) nodejs function get_persistentSettings( ) php cpp m pas function get_persistentSettings( )

Y_PERSISTENTSETTINGS_enum get_persistentSettings( )

-(Y_PERSISTENTSETTINGS_enum) persistentSettings function get_persistentSettings( ): Integer vb cs java py cmd function get_persistentSettings( ) As Integer int get_persistentSettings( ) int get_persistentSettings( ) def get_persistentSettings( )

YModule

target

get_persistentSettings

YModule

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 returns Y_PERSISTENTSETTINGS_INVALID .

168 www.yoctopuce.com

module

→

get_productId() module

→

productId()

Returns the USB device identifier of the module.

js nodejs function get_productId( ) function get_productId( ) php cpp function get_productId( ) int get_productId( ) m pas vb cs

-(int) productId function get_productId( ): LongInt function get_productId( ) As Integer int get_productId( ) java py cmd int get_productId( ) def get_productId( )

YModule

target

get_productId

Returns :

an integer corresponding to the USB device identifier of the module

On failure, throws an exception or returns Y_PRODUCTID_INVALID .

21. High-level API Reference

YModule

www.yoctopuce.com

169

21. High-level API Reference

module

→

get_productName() module

→

productName()

Returns the commercial name of the module, as set by the factory.

js function get_productName( ) nodejs function get_productName( ) php cpp m pas function get_productName( ) string get_productName( )

-(NSString*) productName function get_productName( ): string vb cs java py cmd 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 .

YModule

170 www.yoctopuce.com

module

→

get_productRelease() module

→

productRelease()

Returns the hardware release version of the module.

js nodejs function get_productRelease( ) function get_productRelease( ) php cpp function get_productRelease( ) int get_productRelease( ) m pas vb cs

-(int) productRelease function get_productRelease( ): LongInt function get_productRelease( ) As Integer int get_productRelease( ) java py cmd 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 .

21. High-level API Reference

YModule

www.yoctopuce.com

171

21. High-level API Reference

module

→

get_rebootCountdown() module

→

rebootCountdown()

YModule

Returns the remaining number of seconds before the module restarts, or zero when no reboot has been scheduled.

js function get_rebootCountdown( ) nodejs function get_rebootCountdown( ) php cpp m pas function get_rebootCountdown( ) int get_rebootCountdown( )

-(int) rebootCountdown function get_rebootCountdown( ): LongInt vb cs java py cmd 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

module

→

get_serialNumber() module

→

serialNumber()

Returns the serial number of the module, as set by the factory.

js nodejs function get_serialNumber( ) function get_serialNumber( ) php cpp function get_serialNumber( ) string get_serialNumber( ) m pas vb cs

-(NSString*) serialNumber function get_serialNumber( ): string function get_serialNumber( ) As String string get_serialNumber( ) java py cmd

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_SERIALNUMBER_INVALID .

21. High-level API Reference

YModule

www.yoctopuce.com

173

21. High-level API Reference

module

→

get_upTime() module

→

upTime()

Returns the number of milliseconds spent since the module was powered on.

js function get_upTime( ) nodejs function get_upTime( ) php cpp m pas function get_upTime( ) s64 get_upTime( )

-(s64) upTime function get_upTime( ): int64 vb cs java py cmd 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 .

YModule

174 www.yoctopuce.com

module

→

get_usbBandwidth() module

→

usbBandwidth()

Returns the number of USB interfaces used by the module.

js nodejs function get_usbBandwidth( ) function get_usbBandwidth( ) php cpp function get_usbBandwidth( )

Y_USBBANDWIDTH_enum get_usbBandwidth( ) m pas vb cs

-(Y_USBBANDWIDTH_enum) usbBandwidth function get_usbBandwidth( ): Integer function get_usbBandwidth( ) As Integer int get_usbBandwidth( ) java py cmd int get_usbBandwidth( ) def get_usbBandwidth( )

YModule

target

get_usbBandwidth

21. High-level API Reference

YModule

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

→

get_usbCurrent() module

→

usbCurrent()

Returns the current consumed by the module on the USB bus, in milli-amps.

js function get_usbCurrent( ) nodejs function get_usbCurrent( ) php cpp m pas function get_usbCurrent( ) int get_usbCurrent( )

-(int) usbCurrent function get_usbCurrent( ): LongInt vb cs java py cmd 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 .

YModule

176 www.yoctopuce.com

21. High-level API Reference

module

→

get_userData() module

→

userData()

YModule

Returns the value of the userData attribute, as previously stored using method set_userData

js function get_userData( ) nodejs function get_userData( ) php function get_userData( ) cpp m pas vb cs java py 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

→

isOnline() YModule

Checks if the module is currently reachable, without raising any error.

js function isOnline( ) nodejs function isOnline( ) php function isOnline( ) cpp m pas vb cs java py bool isOnline( )

-(BOOL) isOnline function isOnline( ): boolean function isOnline( ) As Boolean bool isOnline( ) 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

→

isOnline_async() YModule

Checks if the module is currently reachable, without raising any error.

js function isOnline_async(

callback

context

) nodejs function isOnline_async(

callback

context

)

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.

js function load(

msValidity

) nodejs function load(

msValidity

) php function load(

$msValidity

) cpp m pas vb cs java py

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

)

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).

js function load_async(

msValidity

callback

context

) nodejs 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 code

(or

YAPI_SUCCESS

)

context

caller-specific object that is passed as-is to the callback function

Returns :

nothing : the result is provided to the callback.

www.yoctopuce.com

181

21. High-level API Reference

module

→

nextModule()

Continues the module enumeration started using yFirstModule()

js function nextModule( ) nodejs function nextModule( ) php cpp m pas function nextModule( )

YModule * nextModule( )

-(YModule*) nextModule function nextModule( ): TYModule vb cs java py function nextModule( ) As YModule

YModule nextModule( )

YModule nextModule( ) def nextModule( )

YModule

Returns :

a pointer to a

YModule

object, corresponding to the next module found, or a null

pointer if there are no more modules to enumerate.

182 www.yoctopuce.com

module

→

reboot()

Schedules a simple module reboot after the given number of seconds.

js function reboot(

secBeforeReboot

) nodejs function reboot(

secBeforeReboot

) php function reboot(

$secBeforeReboot

) cpp m pas vb cs java py cmd 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

21. High-level API Reference

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

183

21. High-level API Reference

module

→

revertFromFlash() YModule

Reloads the settings stored in the nonvolatile memory, as when the module is powered on.

js function revertFromFlash( ) nodejs function revertFromFlash( ) php function revertFromFlash( ) cpp m pas vb cs java py cmd int revertFromFlash( )

-(int) revertFromFlash function revertFromFlash( ): LongInt function revertFromFlash( ) As Integer int revertFromFlash( ) 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() YModule

Saves current settings in the nonvolatile memory of the module.

js function saveToFlash( ) nodejs function saveToFlash( ) php function saveToFlash( ) cpp m pas vb cs java py cmd int saveToFlash( )

-(int) saveToFlash function saveToFlash( ): LongInt function saveToFlash( ) As Integer int saveToFlash( ) int saveToFlash( ) def saveToFlash( )

YModule

target

saveToFlash

Warning: the number of allowed save operations during a module life is limited (about 100000 cycles).

Do not call this function within a loop.

Returns :

YAPI_SUCCESS when the call succeeds. On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

185

21. High-level API Reference

module

→

set_beacon() module

→

setBeacon()

Turns on or off the module localization beacon.

js function set_beacon(

newval

) nodejs function set_beacon(

newval

) php cpp m pas function set_beacon(

$newval

) int set_beacon( Y_BEACON_enum

newval

)

-(int) setBeacon : (Y_BEACON_enum)

newval

function set_beacon(

newval

: Integer): integer vb cs java py cmd 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

Y_BEACON_ON

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

YModule

186 www.yoctopuce.com

21. High-level API Reference

module

→

set_logicalName() module

→

setLogicalName()

Changes the logical name of the module.

js nodejs function set_logicalName(

newval

) function set_logicalName(

newval

) php cpp function set_logicalName(

$newval

) int set_logicalName( const string&

newval

) m pas vb cs

-(int) setLogicalName : (NSString*)

newval

function set_logicalName(

newval

: string): integer function set_logicalName( ByVal

newval

As String) As Integer int set_logicalName( string

newval

) java py cmd int set_logicalName( String

newval

) def set_logicalName(

newval

)

YModule

target

set_logicalName

newval

YModule

You can use yCheckLogicalName()

prior to this call to make sure that your parameter is valid.

Remember to call the saveToFlash()

method of the module if the modification must be kept.

Parameters : newval

a string corresponding to the logical name of the module

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

187

21. High-level API Reference

module

→

set_luminosity() module

→

setLuminosity()

Changes the luminosity of the module informative leds.

js function set_luminosity(

newval

) nodejs function set_luminosity(

newval

) php cpp m pas function set_luminosity(

$newval

) int set_luminosity( int

newval

)

-(int) setLuminosity : (int)

newval

function set_luminosity(

newval

: LongInt): integer vb cs java py cmd 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

YModule

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

module

→

set_usbBandwidth() module

→

setUsbBandwidth()

Changes the number of USB interfaces used by the module.

js nodejs function set_usbBandwidth(

newval

) function set_usbBandwidth(

newval

) php cpp function set_usbBandwidth(

$newval

) int set_usbBandwidth( Y_USBBANDWIDTH_enum

newval

) m pas vb cs

-(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

) java py cmd int set_usbBandwidth( int

newval

) def set_usbBandwidth(

newval

)

YModule

target

set_usbBandwidth

newval

You must reboot the module after changing this setting.

21. High-level API Reference

YModule

Parameters : newval

either

Y_USBBANDWIDTH_SIMPLE

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() module

→

setUserData()

Stores a user context provided as argument in the userData attribute of the function.

js function set_userData(

data

) nodejs function set_userData(

data

) php cpp m pas function set_userData(

$data

) void set_userData( void*

data

)

-(void) setUserData : (void*)

data

procedure set_userData(

data

: Tobject) vb cs java py 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.

YModule

Parameters : data

any kind of object to be stored

190 www.yoctopuce.com

module

→

triggerFirmwareUpdate()

Schedules a module reboot into special firmware update mode.

js function triggerFirmwareUpdate(

secBeforeReboot

) nodejs function triggerFirmwareUpdate(

secBeforeReboot

) php function triggerFirmwareUpdate(

$secBeforeReboot

) cpp m pas vb cs java py cmd 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

21. High-level API Reference

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 userprovided callback function.

js function wait_async(

callback

context

) nodejs 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.

192 www.yoctopuce.com

21. High-level API Reference

21.3. Display function interface

In order to use the functions described here, you should include: js nodejs php cpp m pas vb cs java py

#include "yocto_display.h"

#import "yocto_display.h" uses yocto_display; yocto_display.vb

yocto_display.cs

import com.yoctopuce.YoctoAPI.YDisplay; from yocto_display import *

Global functions

yFindDisplay(

func

)

Retrieves a display for a given identifier.

yFirstDisplay()

Starts the enumeration of displays currently accessible.

YDisplay

methods

display

copyLayerContent(

srcLayerId

dstLayerId

)

Copies the whole content of a layer to another layer.

display

Returns a short text that describes the display in the form

TYPE(NAME)=SERIAL.FUNCTIONID

display

fade(

brightness

duration

)

Smoothly changes the brightness of the screen to produce a fade-in or fade-out effect.

display

get_advertisedValue()

Returns the current value of the display (no more than 6 characters).

display

get_brightness()

Returns the luminosity of the module informative leds (from 0 to 100).

display

get_displayHeight()

Returns the display height, in pixels.

display

get_displayLayer(

layerId

)

Returns a YDisplayLayer object that can be used to draw on the specified layer.

display

get_displayType()

Returns the display type: monochrome, gray levels or full color.

display

get_displayWidth()

Returns the display width, in pixels.

display

get_enabled()

Returns true if the screen is powered, false otherwise.

display

Returns the error message of the latest error with the display.

display

www.yoctopuce.com

193

21. High-level API Reference

Returns the numerical error code of the latest error with the display.

display

get_friendlyName()

Returns a global identifier of the display in the format MODULE_NAME.FUNCTION_NAME

display

get_functionDescriptor()

Returns a unique identifier of type YFUN_DESCR corresponding to the function.

display

get_functionId()

Returns the hardware identifier of the display, without reference to the module.

display

Returns the unique hardware identifier of the display in the form

SERIAL.FUNCTIONID

display

get_layerCount()

Returns the number of available layers to draw on.

display

get_layerHeight()

Returns the height of the layers to draw on, in pixels.

display

get_layerWidth()

Returns the width of the layers to draw on, in pixels.

display

Returns the logical name of the display.

display

get_module()

Gets the YModule object for the device on which the function is located.

display

get_module_async(

callback

context

)

Gets the

YModule

object for the device on which the function is located (asynchronous version).

display

get_orientation()

Returns the currently selected display orientation.

display

get_startupSeq()

Returns the name of the sequence to play when the displayed is powered on.

display

Returns the value of the userData attribute, as previously stored using method set_userData .

display

Checks if the display is currently reachable, without raising any error.

display

callback

context

)

Checks if the display is currently reachable, without raising any error (asynchronous version).

display

msValidity

)

Preloads the display cache with a specified validity duration.

display

msValidity

callback

context

)

Preloads the display cache with a specified validity duration (asynchronous version).

display

newSequence()

Starts to record all display commands into a sequence, for later replay.

display

nextDisplay()

Continues the enumeration of displays started using yFirstDisplay() .

display

pauseSequence(

delay_ms

)

Waits for a specified delay (in milliseconds) before playing next commands in current sequence.

display

playSequence(

sequenceName

)

Replays a display sequence previously recorded using newSequence()

and saveSequence()

display

registerValueCallback(

callback

)

194 www.yoctopuce.com

21. High-level API Reference

Registers the callback function that is invoked on every change of advertised value.

display

resetAll()

Clears the display screen and resets all display layers to their default state.

display

saveSequence(

sequenceName

)

Stops recording display commands and saves the sequence into the specified file on the display internal memory.

display

set_brightness(

newval

)

Changes the brightness of the display.

display

set_enabled(

newval

)

Changes the power state of the display.

display

newval

)

Changes the logical name of the display.

display

set_orientation(

newval

)

Changes the display orientation.

display

set_startupSeq(

newval

)

Changes the name of the sequence to play when the displayed is powered on.

display

data

)

Stores a user context provided as argument in the userData attribute of the function.

display

stopSequence()

Stops immediately any ongoing sequence replay.

display

swapLayerContent(

layerIdA

layerIdB

)

Swaps the whole content of two layers.

display

upload(

pathname

content

)

Uploads an arbitrary file (for instance a GIF file) to the display, to the specified full path name.

display

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

YDisplay.FindDisplay() yFindDisplay()

Retrieves a display for a given identifier.

js function yFindDisplay(

func

) nodejs function FindDisplay(

func

) php cpp m pas function yFindDisplay(

$func

)

YDisplay* yFindDisplay( string

func

)

+(YDisplay*) yFindDisplay : (NSString*)

func

function yFindDisplay(

func

: string): TYDisplay vb cs java py function yFindDisplay( ByVal

func

As String) As YDisplay

YDisplay FindDisplay( string

func

)

YDisplay FindDisplay( String

func

) def FindDisplay(

func

)

The identifier can be specified using several formats:

YDisplay

●

FunctionLogicalName

●

ModuleSerialNumber.FunctionIdentifier

●

ModuleSerialNumber.FunctionLogicalName

●

ModuleLogicalName.FunctionIdentifier

●

ModuleLogicalName.FunctionLogicalName

This function does not require that the display is online at the time it is invoked. The returned object is nevertheless valid. Use the method YDisplay.isOnline() to test if the display is indeed online at a given time. In case of ambiguity when looking for a display 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 display

Returns :

YDisplay

object allowing you to drive the display.

196 www.yoctopuce.com

YDisplay.FirstDisplay() yFirstDisplay()

Starts the enumeration of displays currently accessible.

js nodejs function yFirstDisplay( ) function FirstDisplay( ) php cpp function yFirstDisplay( )

YDisplay* yFirstDisplay( ) m pas vb cs java py

YDisplay* yFirstDisplay( ) function yFirstDisplay( ): TYDisplay function yFirstDisplay( ) As YDisplay

YDisplay FirstDisplay( )

YDisplay FirstDisplay( ) def FirstDisplay( )

Use the method

YDisplay.nextDisplay()

to iterate on next displays.

21. High-level API Reference

YDisplay

Returns :

a pointer to a YDisplay object, corresponding to the first display currently online, or a null pointer if there are none.

www.yoctopuce.com

197

21. High-level API Reference

display

→

copyLayerContent() YDisplay

Copies the whole content of a layer to another layer.

js function copyLayerContent(

srcLayerId

dstLayerId

) nodejs function copyLayerContent(

srcLayerId

dstLayerId

) php function copyLayerContent(

$srcLayerId

$dstLayerId

) cpp m int copyLayerContent( int

srcLayerId

, int

dstLayerId

)

-(int) copyLayerContent : (int)

srcLayerId

: (int)

dstLayerId

pas function copyLayerContent(

srcLayerId

: LongInt,

dstLayerId

: LongInt): LongInt vb cs java py cmd function copyLayerContent( ) As Integer int copyLayerContent( int

srcLayerId

, int

dstLayerId

) int copyLayerContent( int

srcLayerId

, int

dstLayerId

) def copyLayerContent(

srcLayerId

dstLayerId

)

YDisplay

target

copyLayerContent

srcLayerId dstLayerId

The color and transparency of all the pixels from the destination layer are set to match the source pixels. This method only affects the displayed content, but does not change any property of the layer object. Note that layer 0 has no transparency support (it is always completely opaque).

Parameters : srcLayerId

the identifier of the source layer (a number in range 0..layerCount-1)

dstLayerId

the identifier of the destination layer (a number in range 0..layerCount-1)

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

198 www.yoctopuce.com

21. High-level API Reference

display

→

describe() YDisplay

Returns a short text that describes the display in the form

TYPE(NAME)=SERIAL.FUNCTIONID

js nodejs function describe( ) function describe( ) php cpp function describe( ) string describe( ) m pas vb cs java py

-(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.relay1)=RELAYLO1-123456.relay1

if the module is already connected or

Relay(BadCustomeName.relay1)=unresolved

if the module has not yet been connected. This method does not trigger any USB or TCP transaction and can therefore be used in a debugger.

Returns :

a string that describes the display (ex:

Relay(MyCustomName.relay1)=RELAYLO1-

123456.relay1

)

www.yoctopuce.com

199

21. High-level API Reference

display

→

fade()

Smoothly changes the brightness of the screen to produce a fade-in or fade-out effect.

js function fade(

brightness

duration

) nodejs function fade(

brightness

duration

) php function fade(

$brightness

$duration

) cpp m pas vb cs java py cmd int fade( int

brightness

, int

duration

)

-(int) fade : (int)

brightness

: (int)

duration

function fade(

brightness

: LongInt,

duration

: LongInt): LongInt function fade( ) As Integer int fade( int

brightness

, int

duration

) int fade( int

brightness

, int

duration

) def fade(

brightness

duration

)

YDisplay

target

fade

brightness duration

YDisplay

Parameters : brightness

the new screen brightness

duration

duration of the brightness transition, in milliseconds.

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

200 www.yoctopuce.com

display

→

get_advertisedValue() display

→

advertisedValue()

Returns the current value of the display (no more than 6 characters).

js nodejs function get_advertisedValue( ) function get_advertisedValue( ) php cpp function get_advertisedValue( ) string get_advertisedValue( ) m pas vb cs

-(NSString*) advertisedValue function get_advertisedValue( ): string function get_advertisedValue( ) As String string get_advertisedValue( ) java py cmd

String get_advertisedValue( ) def get_advertisedValue( )

YDisplay

target

get_advertisedValue

21. High-level API Reference

YDisplay

Returns :

a string corresponding to the current value of the display (no more than 6 characters). On failure, throws an exception or returns

Y_ADVERTISEDVALUE_INVALID

www.yoctopuce.com

201

21. High-level API Reference

display

→

get_brightness() display

→

brightness()

Returns the luminosity of the module informative leds (from 0 to 100).

js function get_brightness( ) nodejs function get_brightness( ) php cpp m pas function get_brightness( ) int get_brightness( )

-(int) brightness function get_brightness( ): LongInt vb cs java py cmd function get_brightness( ) As Integer int get_brightness( ) int get_brightness( ) def get_brightness( )

YDisplay

target

get_brightness

Returns :

an integer corresponding to the luminosity of the module informative leds (from 0 to 100)

On failure, throws an exception or returns Y_BRIGHTNESS_INVALID .

YDisplay

202 www.yoctopuce.com

display

→

get_displayHeight() display

→

displayHeight()

Returns the display height, in pixels.

js nodejs function get_displayHeight( ) function get_displayHeight( ) php cpp function get_displayHeight( ) int get_displayHeight( ) m pas vb cs

-(int) displayHeight function get_displayHeight( ): LongInt function get_displayHeight( ) As Integer int get_displayHeight( ) java py cmd int get_displayHeight( ) def get_displayHeight( )

YDisplay

target

get_displayHeight

Returns :

an integer corresponding to the display height, in pixels

On failure, throws an exception or returns Y_DISPLAYHEIGHT_INVALID .

21. High-level API Reference

YDisplay

www.yoctopuce.com

203

21. High-level API Reference

display

→

get_displayLayer() display

→

displayLayer()

YDisplay

Returns a YDisplayLayer object that can be used to draw on the specified layer.

js function get_displayLayer(

layerId

) nodejs function get_displayLayer(

layerId

) php cpp m vb cs java function get_displayLayer(

$layerId

)

YDisplayLayer* get_displayLayer( unsigned

layerId

)

-(YDisplayLayer*) displayLayer : (unsigned)

layerId

function get_displayLayer( ) As YDisplayLayer

YDisplayLayer get_displayLayer( int

layerId

) synchronized YDisplayLayer get_displayLayer( int

layerId

)

The content is displayed only when the layer is active on the screen (and not masked by other overlapping layers).

Parameters : layerId

the identifier of the layer (a number in range 0..layerCount-1)

Returns :

YDisplayLayer

object

On failure, throws an exception or returns null .

204 www.yoctopuce.com

display

→

get_displayType() display

→

displayType()

Returns the display type: monochrome, gray levels or full color.

js nodejs function get_displayType( ) function get_displayType( ) php cpp function get_displayType( )

Y_DISPLAYTYPE_enum get_displayType( ) m pas vb cs

-(Y_DISPLAYTYPE_enum) displayType function get_displayType( ): Integer function get_displayType( ) As Integer int get_displayType( ) java py cmd int get_displayType( ) def get_displayType( )

YDisplay

target

get_displayType

21. High-level API Reference

YDisplay

Returns :

a value among Y_DISPLAYTYPE_MONO , Y_DISPLAYTYPE_GRAY and Y_DISPLAYTYPE_RGB corresponding to the display type: monochrome, gray levels or full color

On failure, throws an exception or returns

Y_DISPLAYTYPE_INVALID

www.yoctopuce.com

205

21. High-level API Reference

display

→

get_displayWidth() display

→

displayWidth()

Returns the display width, in pixels.

js function get_displayWidth( ) nodejs function get_displayWidth( ) php cpp m pas function get_displayWidth( ) int get_displayWidth( )

-(int) displayWidth function get_displayWidth( ): LongInt vb cs java py cmd function get_displayWidth( ) As Integer int get_displayWidth( ) int get_displayWidth( ) def get_displayWidth( )

YDisplay

target

get_displayWidth

Returns :

an integer corresponding to the display width, in pixels

On failure, throws an exception or returns Y_DISPLAYWIDTH_INVALID .

YDisplay

206 www.yoctopuce.com

display

→

get_enabled() display

→

enabled()

Returns true if the screen is powered, false otherwise.

js nodejs function get_enabled( ) function get_enabled( ) php cpp function get_enabled( )

Y_ENABLED_enum get_enabled( ) m pas vb cs

-(Y_ENABLED_enum) enabled function get_enabled( ): Integer function get_enabled( ) As Integer int get_enabled( ) java py cmd int get_enabled( ) def get_enabled( )

YDisplay

target

get_enabled

21. High-level API Reference

YDisplay

Returns :

either Y_ENABLED_FALSE or Y_ENABLED_TRUE , according to true if the screen is powered, false otherwise

On failure, throws an exception or returns

Y_ENABLED_INVALID

www.yoctopuce.com

207

21. High-level API Reference

display

→

get_errorMessage() display

→

errorMessage()

Returns the error message of the latest error with the display.

js function get_errorMessage( ) nodejs function get_errorMessage( ) php cpp m pas function get_errorMessage( ) string get_errorMessage( )

-(NSString*) errorMessage function get_errorMessage( ): string vb cs java py 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.

YDisplay

Returns :

a string corresponding to the latest error message that occured while using the display object

208 www.yoctopuce.com

21. High-level API Reference

display

→

get_errorType() display

→

errorType()

Returns the numerical error code of the latest error with the display.

js nodejs function get_errorType( ) function get_errorType( ) php cpp function get_errorType( )

YRETCODE get_errorType( ) pas vb cs java py 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.

YDisplay

Returns :

a number corresponding to the code of the latest error that occured while using the display object

www.yoctopuce.com

209

21. High-level API Reference

display

→

get_friendlyName() display

→

friendlyName()

YDisplay

Returns a global identifier of the display in the format

MODULE_NAME.FUNCTION_NAME

js function get_friendlyName( ) nodejs function get_friendlyName( ) php function get_friendlyName( ) cpp m cs java py 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 display if they are defined, otherwise the serial number of the module and the hardware identifier of the display (for exemple:

MyCustomName.relay1

)

Returns :

a string that uniquely identifies the display using logical names (ex: MyCustomName.relay1

) On failure, throws an exception or returns

Y_FRIENDLYNAME_INVALID

210 www.yoctopuce.com

21. High-level API Reference

display

→

get_functionDescriptor() display

→

functionDescriptor()

YDisplay

Returns a unique identifier of type

YFUN_DESCR

corresponding to the function.

js function get_functionDescriptor( ) nodejs function get_functionDescriptor( ) php function get_functionDescriptor( ) cpp m pas vb cs java py

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

www.yoctopuce.com

211

21. High-level API Reference

display

→

get_functionId() display

→

functionId()

Returns the hardware identifier of the display, without reference to the module.

js function get_functionId( ) nodejs function get_functionId( ) php cpp m vb function get_functionId( ) string get_functionId( )

-(NSString*) functionId function get_functionId( ) As String cs java py string get_functionId( )

String get_functionId( ) def get_functionId( )

For example relay1

YDisplay

Returns :

a string that identifies the display (ex: relay1 ) On failure, throws an exception or returns

Y_FUNCTIONID_INVALID

212 www.yoctopuce.com

21. High-level API Reference

display

→

get_hardwareId() display

→

hardwareId()

YDisplay

Returns the unique hardware identifier of the display in the form

SERIAL.FUNCTIONID

js function get_hardwareId( ) nodejs function get_hardwareId( ) php function get_hardwareId( ) cpp m vb cs java py string get_hardwareId( )

-(NSString*) hardwareId function get_hardwareId( ) As String string get_hardwareId( )

String get_hardwareId( ) def get_hardwareId( )

The unique hardware identifier is composed of the device serial number and of the hardware identifier of the display. (for example

RELAYLO1-123456.relay1

)

Returns :

a string that uniquely identifies the display (ex:

RELAYLO1-123456.relay1

) On failure, throws an exception or returns Y_HARDWAREID_INVALID .

www.yoctopuce.com

213

21. High-level API Reference

display

→

get_layerCount() display

→

layerCount()

Returns the number of available layers to draw on.

js function get_layerCount( ) nodejs function get_layerCount( ) php cpp m pas function get_layerCount( ) int get_layerCount( )

-(int) layerCount function get_layerCount( ): LongInt vb cs java py cmd function get_layerCount( ) As Integer int get_layerCount( ) int get_layerCount( ) def get_layerCount( )

YDisplay

target

get_layerCount

Returns :

an integer corresponding to the number of available layers to draw on

On failure, throws an exception or returns Y_LAYERCOUNT_INVALID .

YDisplay

214 www.yoctopuce.com

display

→

get_layerHeight() display

→

layerHeight()

Returns the height of the layers to draw on, in pixels.

js nodejs function get_layerHeight( ) function get_layerHeight( ) php cpp function get_layerHeight( ) int get_layerHeight( ) m pas vb cs

-(int) layerHeight function get_layerHeight( ): LongInt function get_layerHeight( ) As Integer int get_layerHeight( ) java py cmd int get_layerHeight( ) def get_layerHeight( )

YDisplay

target

get_layerHeight

Returns :

an integer corresponding to the height of the layers to draw on, in pixels

On failure, throws an exception or returns Y_LAYERHEIGHT_INVALID .

21. High-level API Reference

YDisplay

www.yoctopuce.com

215

21. High-level API Reference

display

→

get_layerWidth() display

→

layerWidth()

Returns the width of the layers to draw on, in pixels.

js function get_layerWidth( ) nodejs function get_layerWidth( ) php cpp m pas function get_layerWidth( ) int get_layerWidth( )

-(int) layerWidth function get_layerWidth( ): LongInt vb cs java py cmd function get_layerWidth( ) As Integer int get_layerWidth( ) int get_layerWidth( ) def get_layerWidth( )

YDisplay

target

get_layerWidth

Returns :

an integer corresponding to the width of the layers to draw on, in pixels

On failure, throws an exception or returns Y_LAYERWIDTH_INVALID .

YDisplay

216 www.yoctopuce.com

display

→

get_logicalName() display

→

logicalName()

Returns the logical name of the display.

js nodejs function get_logicalName( ) function get_logicalName( ) php cpp function get_logicalName( ) string get_logicalName( ) m pas vb cs

-(NSString*) logicalName function get_logicalName( ): string function get_logicalName( ) As String string get_logicalName( ) java py cmd

String get_logicalName( ) def get_logicalName( )

YDisplay

target

get_logicalName

21. High-level API Reference

YDisplay

Returns :

a string corresponding to the logical name of the display. On failure, throws an exception or returns

Y_LOGICALNAME_INVALID

www.yoctopuce.com

217

21. High-level API Reference

display

→

get_module() display

→

module()

YDisplay

Gets the

YModule

object for the device on which the function is located.

js function get_module( ) nodejs function get_module( ) php function get_module( ) cpp m pas vb cs java py

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 module, the returned instance of

YModule

is not shown as online.

Returns :

an instance of YModule

218 www.yoctopuce.com

21. High-level API Reference

display

→

get_module_async() display

→

module_async()

YDisplay

Gets the

YModule

object for the device on which the function is located (asynchronous version).

js function get_module_async(

callback

context

) nodejs function get_module_async(

callback

context

)

If the function cannot be located on any module, the returned

YModule

object does not show as online. 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

219

21. High-level API Reference

display

→

get_orientation() display

→

orientation()

Returns the currently selected display orientation.

js function get_orientation( ) nodejs function get_orientation( ) php cpp m pas function get_orientation( )

Y_ORIENTATION_enum get_orientation( )

-(Y_ORIENTATION_enum) orientation function get_orientation( ): Integer vb cs java py cmd function get_orientation( ) As Integer int get_orientation( ) int get_orientation( ) def get_orientation( )

YDisplay

target

get_orientation

YDisplay

Returns :

a value among Y_ORIENTATION_LEFT , Y_ORIENTATION_UP , Y_ORIENTATION_RIGHT and

Y_ORIENTATION_DOWN corresponding to the currently selected display orientation

On failure, throws an exception or returns Y_ORIENTATION_INVALID .

220 www.yoctopuce.com

display

→

get_startupSeq() display

→

startupSeq()

Returns the name of the sequence to play when the displayed is powered on.

js nodejs function get_startupSeq( ) function get_startupSeq( ) php cpp function get_startupSeq( ) string get_startupSeq( ) m pas vb cs

-(NSString*) startupSeq function get_startupSeq( ): string function get_startupSeq( ) As String string get_startupSeq( ) java py cmd

String get_startupSeq( ) def get_startupSeq( )

YDisplay

target

get_startupSeq

21. High-level API Reference

YDisplay

Returns :

a string corresponding to the name of the sequence to play when the displayed is powered on

On failure, throws an exception or returns Y_STARTUPSEQ_INVALID .

www.yoctopuce.com

221

21. High-level API Reference

display

→

get_userData() display

→

userData()

YDisplay

Returns the value of the userData attribute, as previously stored using method set_userData

js function get_userData( ) nodejs function get_userData( ) php function get_userData( ) cpp m pas vb cs java py 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.

222 www.yoctopuce.com

21. High-level API Reference

display

→

isOnline() YDisplay

Checks if the display is currently reachable, without raising any error.

js function isOnline( ) nodejs function isOnline( ) php function isOnline( ) cpp m pas vb cs java py 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 display 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 display.

Returns :

true

if the display can be reached, and false

otherwise

www.yoctopuce.com

223

21. High-level API Reference

display

→

isOnline_async() YDisplay

Checks if the display is currently reachable, without raising any error (asynchronous version).

js function isOnline_async(

callback

context

) nodejs function isOnline_async(

callback

context

)

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.

224 www.yoctopuce.com

21. High-level API Reference

display

→

load() YDisplay

Preloads the display cache with a specified validity duration.

js function load(

msValidity

) nodejs function load(

msValidity

) php function load(

$msValidity

) cpp m pas vb cs java py

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

)

Parameters : msValidity

an integer corresponding to the validity attributed to the loaded function parameters, in milliseconds

Returns :

YAPI_SUCCESS when the call succeeds. On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

225

21. High-level API Reference

display

→

load_async() YDisplay

Preloads the display cache with a specified validity duration (asynchronous version).

js function load_async(

msValidity

callback

context

) nodejs 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

YAPI_SUCCESS

)

context

caller-specific object that is passed as-is to the callback function

Returns :

nothing : the result is provided to the callback.

226 www.yoctopuce.com

21. High-level API Reference

display

→

newSequence()

Starts to record all display commands into a sequence, for later replay.

js function newSequence( ) nodejs function newSequence( ) php function newSequence( ) cpp m pas vb cs java py cmd int newSequence( )

-(int) newSequence function newSequence( ): LongInt function newSequence( ) As Integer int newSequence( ) int newSequence( ) def newSequence( )

YDisplay

target

newSequence

YDisplay

The name used to store the sequence is specified when calling saveSequence()

, once the recording is complete.

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

227

21. High-level API Reference

display

→

nextDisplay()

Continues the enumeration of displays started using yFirstDisplay()

js function nextDisplay( ) nodejs function nextDisplay( ) php cpp m pas function nextDisplay( )

YDisplay * nextDisplay( )

-(YDisplay*) nextDisplay function nextDisplay( ): TYDisplay vb cs java py function nextDisplay( ) As YDisplay

YDisplay nextDisplay( )

YDisplay nextDisplay( ) def nextDisplay( )

YDisplay

Returns :

a pointer to a

YDisplay

object, corresponding to a display currently online, or a null

pointer if there are no more displays to enumerate.

228 www.yoctopuce.com

21. High-level API Reference

display

→

pauseSequence() YDisplay

Waits for a specified delay (in milliseconds) before playing next commands in current sequence.

js function pauseSequence(

delay_ms

) nodejs function pauseSequence(

delay_ms

) php function pauseSequence(

$delay_ms

) cpp m pas vb cs java py cmd int pauseSequence( int

delay_ms

)

-(int) pauseSequence : (int)

delay_ms

function pauseSequence(

delay_ms

: LongInt): LongInt function pauseSequence( ) As Integer int pauseSequence( int

delay_ms

) int pauseSequence( int

delay_ms

) def pauseSequence(

delay_ms

)

YDisplay

target

pauseSequence

delay_ms

This method can be used while recording a display sequence, to insert a timed wait in the sequence

(without any immediate effect). It can also be used dynamically while playing a pre-recorded sequence, to suspend or resume the execution of the sequence. To cancel a delay, call the same method with a zero delay.

Parameters : delay_ms

the duration to wait, in milliseconds

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

229

21. High-level API Reference

display

→

playSequence() YDisplay

Replays a display sequence previously recorded using newSequence()

and saveSequence()

js function playSequence(

sequenceName

) nodejs function playSequence(

sequenceName

) php cpp m pas function playSequence(

$sequenceName

) int playSequence( string

sequenceName

)

-(int) playSequence : (NSString*)

sequenceName

function playSequence(

sequenceName

: string): LongInt vb cs java py cmd function playSequence( ) As Integer int playSequence( string

sequenceName

) int playSequence( String

sequenceName

) def playSequence(

sequenceName

)

YDisplay

target

playSequence

sequenceName

Parameters : sequenceName

the name of the newly created sequence

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

230 www.yoctopuce.com

21. High-level API Reference

display

→

registerValueCallback()

Registers the callback function that is invoked on every change of advertised value.

js function registerValueCallback(

callback

) nodejs function registerValueCallback(

callback

) php function registerValueCallback(

$callback

) cpp m pas vb cs java py int registerValueCallback( YDisplayValueCallback

callback

)

-(int) registerValueCallback : (YDisplayValueCallback)

callback

function registerValueCallback(

callback

: TYDisplayValueCallback): LongInt function registerValueCallback( ) As Integer int registerValueCallback( ValueCallback

callback

) int registerValueCallback( UpdateCallback

callback

) def registerValueCallback(

callback

)

YDisplay

The callback is invoked only during the execution of ySleep

or yHandleEvents

. This provides control over the time when the callback is triggered. For good responsiveness, remember to call one of these two functions periodically. To unregister a callback, pass a null pointer as argument.

Parameters : callback

the callback function to call, or a null pointer. The callback function should take two arguments: the function object of which the value has changed, and the character string describing the new advertised value.

www.yoctopuce.com

231

21. High-level API Reference

display

→

resetAll()

Clears the display screen and resets all display layers to their default state.

js function resetAll( ) nodejs function resetAll( ) php function resetAll( ) cpp m pas vb cs java py cmd int resetAll( )

-(int) resetAll function resetAll( ): LongInt function resetAll( ) As Integer int resetAll( ) int resetAll( ) def resetAll( )

YDisplay

target

resetAll

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

YDisplay

232 www.yoctopuce.com

21. High-level API Reference

display

→

saveSequence() YDisplay

Stops recording display commands and saves the sequence into the specified file on the display internal memory.

js function saveSequence(

sequenceName

) nodejs function saveSequence(

sequenceName

) php function saveSequence(

$sequenceName

) cpp m pas vb cs java py cmd int saveSequence( string

sequenceName

)

-(int) saveSequence : (NSString*)

sequenceName

function saveSequence(

sequenceName

: string): LongInt function saveSequence( ) As Integer int saveSequence( string

sequenceName

) int saveSequence( String

sequenceName

) def saveSequence(

sequenceName

)

YDisplay

target

saveSequence

sequenceName

The sequence can be later replayed using playSequence()

Parameters : sequenceName

the name of the newly created sequence

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

233

21. High-level API Reference

display

→

set_brightness() display

→

setBrightness()

Changes the brightness of the display.

js function set_brightness(

newval

) nodejs function set_brightness(

newval

) php cpp m pas function set_brightness(

$newval

) int set_brightness( int

newval

)

-(int) setBrightness : (int)

newval

function set_brightness(

newval

: LongInt): integer vb cs java py cmd function set_brightness( ByVal

newval

As Integer) As Integer int set_brightness( int

newval

) int set_brightness( int

newval

) def set_brightness(

newval

)

YDisplay

target

set_brightness

newval

YDisplay

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 brightness of the display

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

234 www.yoctopuce.com

display

→

set_enabled() display

→

setEnabled()

Changes the power state of the display.

js nodejs function set_enabled(

newval

) function set_enabled(

newval

) php cpp function set_enabled(

$newval

) int set_enabled( Y_ENABLED_enum

newval

) m pas vb cs

-(int) setEnabled : (Y_ENABLED_enum)

newval

function set_enabled(

newval

: Integer): integer function set_enabled( ByVal

newval

As Integer) As Integer int set_enabled( int

newval

) java py cmd int set_enabled( int

newval

) def set_enabled(

newval

)

YDisplay

target

set_enabled

newval

21. High-level API Reference

YDisplay

Parameters : newval

either

Y_ENABLED_FALSE

Y_ENABLED_TRUE

, according to the power state of the display

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

235

21. High-level API Reference

display

→

set_logicalName() display

→

setLogicalName()

Changes the logical name of the display.

js function set_logicalName(

newval

) nodejs function set_logicalName(

newval

) php cpp m pas function set_logicalName(

$newval

) int set_logicalName( const string&

newval

)

-(int) setLogicalName : (NSString*)

newval

function set_logicalName(

newval

: string): integer vb cs java py cmd function set_logicalName( ByVal

newval

As String) As Integer int set_logicalName( string

newval

) int set_logicalName( String

newval

) def set_logicalName(

newval

)

YDisplay

target

set_logicalName

newval

YDisplay

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 display.

Returns :

YAPI_SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.

236 www.yoctopuce.com

21. High-level API Reference

display

→

set_orientation() display

→

setOrientation()

Changes the display orientation.

js nodejs function set_orientation(

newval

) function set_orientation(

newval

) php cpp function set_orientation(

$newval

) int set_orientation( Y_ORIENTATION_enum

newval

) m pas vb cs

-(int) setOrientation : (Y_ORIENTATION_enum)

newval

function set_orientation(

newval

: Integer): integer function set_orientation( ByVal

newval

As Integer) As Integer int set_orientation( int

newval

) java py cmd int set_orientation( int

newval

) def set_orientation(

newval

)

YDisplay

target

set_orientation

newval

YDisplay

Remember to call the saveToFlash()

method of the module if the modification must be kept.

Parameters : newval

a v a l u e a m o n g Y _ O R I E N T A T I O N _ L E F T , Y _ O R I E N T A T I O N _ U P ,

Y_ORIENTATION_RIGHT and Y_ORIENTATION_DOWN corresponding to the display orientation

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

237

21. High-level API Reference

display

→

set_startupSeq() display

→

setStartupSeq()

Changes the name of the sequence to play when the displayed is powered on.

js function set_startupSeq(

newval

) nodejs function set_startupSeq(

newval

) php cpp m pas function set_startupSeq(

$newval

) int set_startupSeq( const string&

newval

)

-(int) setStartupSeq : (NSString*)

newval

function set_startupSeq(

newval

: string): integer vb cs java py cmd function set_startupSeq( ByVal

newval

As String) As Integer int set_startupSeq( string

newval

) int set_startupSeq( String

newval

) def set_startupSeq(

newval

)

YDisplay

target

set_startupSeq

newval

YDisplay

Remember to call the saveToFlash()

method of the module if the modification must be kept.

Parameters : newval

a string corresponding to the name of the sequence to play when the displayed is powered on

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

238 www.yoctopuce.com

21. High-level API Reference

display

→

set_userData() display

→

setUserData()

Stores a user context provided as argument in the userData attribute of the function.

js nodejs function set_userData(

data

) function set_userData(

data

) php cpp function set_userData(

$data

) void set_userData( void*

data

) m pas vb cs java py

-(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.

YDisplay

Parameters : data

any kind of object to be stored

www.yoctopuce.com

239

21. High-level API Reference

display

→

stopSequence()

Stops immediately any ongoing sequence replay.

js function stopSequence( ) nodejs function stopSequence( ) php function stopSequence( ) cpp m pas vb cs java py cmd int stopSequence( )

-(int) stopSequence function stopSequence( ): LongInt function stopSequence( ) As Integer int stopSequence( ) int stopSequence( ) def stopSequence( )

YDisplay

target

stopSequence

The display is left as is.

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

YDisplay

240 www.yoctopuce.com

21. High-level API Reference

display

→

swapLayerContent() YDisplay

Swaps the whole content of two layers.

js cpp m function swapLayerContent(

layerIdA

layerIdB

) nodejs function swapLayerContent(

layerIdA

layerIdB

) php function swapLayerContent(

$layerIdA

$layerIdB

) int swapLayerContent( int

layerIdA

, int

layerIdB

)

-(int) swapLayerContent : (int)

layerIdA

: (int)

layerIdB

pas vb cs java py cmd function swapLayerContent(

layerIdA

: LongInt,

layerIdB

: LongInt): LongInt function swapLayerContent( ) As Integer int swapLayerContent( int

layerIdA

, int

layerIdB

) int swapLayerContent( int

layerIdA

, int

layerIdB

) def swapLayerContent(

layerIdA

layerIdB

)

YDisplay

target

swapLayerContent

layerIdA layerIdB

The color and transparency of all the pixels from the two layers are swapped. This method only affects the displayed content, but does not change any property of the layer objects. In particular, the visibility of each layer stays unchanged. When used between onae hidden layer and a visible layer, this method makes it possible to easily implement double-buffering. Note that layer 0 has no transparency support

(it is always completely opaque).

Parameters : layerIdA

the first layer (a number in range 0..layerCount-1)

layerIdB

the second layer (a number in range 0..layerCount-1)

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

241

21. High-level API Reference

display

→

upload() YDisplay

Uploads an arbitrary file (for instance a GIF file) to the display, to the specified full path name.

js function upload(

pathname

content

) nodejs function upload(

pathname

content

) php function upload(

$pathname

$content

) cpp m int upload( string

pathname

, string

content

)

-(int) upload : (NSString*)

pathname

: (NSData*)

content

pas vb cs java py cmd function upload(

pathname

: string,

content

: TByteArray): LongInt procedure upload( ) int upload( string

pathname

) int upload( String

pathname

) def upload(

pathname

content

)

YDisplay

target

upload

pathname content

If a file already exists with the same path name, its content is overwritten.

Parameters : pathname

path and name of the new file to create

content

binary buffer with the content to set

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

242 www.yoctopuce.com

21. High-level API Reference

display

→

wait_async() YDisplay

Waits for all pending asynchronous commands on the module to complete, and invoke the userprovided callback function.

js function wait_async(

callback

context

) nodejs 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

context

caller-specific object that is passed as-is to the callback function

Returns :

nothing.

www.yoctopuce.com

243

21. High-level API Reference

21.4. DisplayLayer object interface

A DisplayLayer is an image layer containing objects to display (bitmaps, text, etc.). The content is displayed only when the layer is active on the screen (and not masked by other overlapping layers).

In order to use the functions described here, you should include: js nodejs php cpp

#include "yocto_display.h" m pas vb cs java py

#import "yocto_display.h" uses yocto_display; yocto_display.vb

yocto_display.cs

import com.yoctopuce.YoctoAPI.YDisplay; from yocto_display import *

YDisplayLayer

methods

clear()

Erases the whole content of the layer (makes it fully transparent).

clearConsole()

Blanks the console area within console margins, and resets the console pointer to the upper left corner of the console.

consoleOut(

text

)

Outputs a message in the console area, and advances the console pointer accordingly.

drawBar(

)

Draws a filled rectangular bar at a specified position.

drawBitmap(

bitmap

bgcol

)

Draws a bitmap at the specified position.

drawCircle(

)

Draws an empty circle at a specified position.

drawDisc(

)

Draws a filled disc at a given position.

drawImage(

imagename

)

Draws a GIF image at the specified position.

drawPixel(

)

Draws a single pixel at the specified position.

drawRect(

)

Draws an empty rectangle at a specified position.

drawText(

anchor

text

)

Draws a text string at the specified position.

get_display()

Gets parent YDisplay.

get_displayHeight()

Returns the display height, in pixels.

get_displayWidth()

Returns the display width, in pixels.

244 www.yoctopuce.com

21. High-level API Reference

get_layerHeight()

Returns the height of the layers to draw on, in pixels.

get_layerWidth()

Returns the width of the layers to draw on, in pixels.

hide()

Hides the layer.

lineTo(

)

Draws a line from current drawing pointer position to the specified position.

moveTo(

)

Moves the drawing pointer of this layer to the specified position.

reset()

Reverts the layer to its initial state (fully transparent, default settings).

selectColorPen(

color

)

Selects the pen color for all subsequent drawing functions, including text drawing.

selectEraser()

Selects an eraser instead of a pen for all subsequent drawing functions, except for text drawing and bitmap copy functions.

selectFont(

fontname

)

Selects a font to use for the next text drawing functions, by providing the name of the font file.

selectGrayPen(

graylevel

)

Selects the pen gray level for all subsequent drawing functions, including text drawing.

setAntialiasingMode(

mode

)

Enables or disables anti-aliasing for drawing oblique lines and circles.

setConsoleBackground(

bgcol

)

Sets up the background color used by the clearConsole

function and by the console scrolling feature.

setConsoleMargins(

)

Sets up display margins for the consoleOut

function.

setConsoleWordWrap(

wordwrap

)

Sets up the wrapping behaviour used by the consoleOut

function.

setLayerPosition(

scrollTime

)

Sets the position of the layer relative to the display upper left corner.

unhide()

Shows the layer.

www.yoctopuce.com

245

21. High-level API Reference

displaylayer

→

clear() YDisplayLayer

Erases the whole content of the layer (makes it fully transparent).

js function clear( ) nodejs function clear( ) php function clear( ) cpp m pas vb cs java py cmd int clear( )

-(int) clear function clear( ): LongInt function clear( ) As Integer int clear( ) int clear( ) def clear( )

YDisplay

target

[-layer

layerId

] clear

This method does not change any other attribute of the layer. To reinitialize the layer attributes to defaults settings, use the method reset()

instead.

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

246 www.yoctopuce.com

21. High-level API Reference

displaylayer

→

clearConsole() YDisplayLayer

Blanks the console area within console margins, and resets the console pointer to the upper left corner of the console.

js function clearConsole( ) nodejs function clearConsole( ) php function clearConsole( ) cpp m pas vb cs java py cmd int clearConsole( )

-(int) clearConsole function clearConsole( ): LongInt function clearConsole( ) As Integer int clearConsole( ) int clearConsole( ) def clearConsole( )

YDisplay

target

[-layer

layerId

] clearConsole

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

247

21. High-level API Reference

displaylayer

→

consoleOut() YDisplayLayer

Outputs a message in the console area, and advances the console pointer accordingly.

js function consoleOut(

text

) nodejs function consoleOut(

text

) php function consoleOut(

$text

) cpp m pas vb cs java py cmd int consoleOut( string

text

)

-(int) consoleOut : (NSString*)

text

function consoleOut(

text

: string): LongInt function consoleOut( ) As Integer int consoleOut( string

text

) int consoleOut( String

text

) def consoleOut(

text

)

YDisplay

target

[-layer

layerId

] consoleOut

text

The console pointer position is automatically moved to the beginning of the next line when a newline character is met, or when the right margin is hit. When the new text to display extends below the lower margin, the console area is automatically scrolled up.

Parameters : text

the message to display

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

248 www.yoctopuce.com

displaylayer

→

drawBar()

Draws a filled rectangular bar at a specified position.

js cpp m function drawBar(

) nodejs function drawBar(

) php function drawBar(

$x1

$y1

$x2

$y2

) int drawBar( int

, int

)

-(int) drawBar : (int)

: (int)

pas function drawBar(

: LongInt,

: LongInt): LongInt vb cs java py cmd function drawBar( ) As Integer int drawBar( int

, int

) int drawBar( int

, int

) def drawBar(

)

YDisplay

target

[-layer

layerId

] drawBar

x1 y1 x2 y2

Parameters : x1

the distance from left of layer to the left border of the rectangle, in pixels

the distance from top of layer to the top border of the rectangle, in pixels

the distance from left of layer to the right border of the rectangle, in pixels

the distance from top of layer to the bottom border of the rectangle, in pixels

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

21. High-level API Reference

YDisplayLayer

www.yoctopuce.com

249

21. High-level API Reference

displaylayer

→

drawBitmap() YDisplayLayer

Draws a bitmap at the specified position.

js function drawBitmap(

bitmap

bgcol

) nodejs function drawBitmap(

bitmap

bgcol

) php function drawBitmap(

$bitmap

$bgcol

) cpp m int drawBitmap( int

, int

, string

bitmap

, int

bgcol

)

-(int) drawBitmap : (int)

: (int)

: (NSData*)

bgcol bitmap

pas function drawBitmap(

: LongInt,

bitmap bgcol

: TByteArray,

: LongInt): LongInt vb cs procedure drawBitmap( ) int drawBitmap( int

, int

bgcol

) java py cmd int drawBitmap( int

, int

bgcol

) def drawBitmap(

bitmap

bgcol

)

YDisplay

target

[-layer

layerId

] drawBitmap

x y w bitmap bgcol

The bitmap is provided as a binary object, where each pixel maps to a bit, from left to right and from top to bottom. The most significant bit of each byte maps to the leftmost pixel, and the least significant bit maps to the rightmost pixel. Bits set to 1 are drawn using the layer selected pen color. Bits set to 0 are drawn using the specified background gray level, unless -1 is specified, in which case they are not drawn at all (as if transparent).

Parameters : x

the distance from left of layer to the left of the bitmap, in pixels

y w

the distance from top of layer to the top of the bitmap, in pixels the width of the bitmap, in pixels

bitmap

a binary object

bgcol

the background gray level to use for zero bits (0 = black, 255 = white), or -1 to leave the pixels unchanged

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

250 www.yoctopuce.com

displaylayer

→

drawCircle()

Draws an empty circle at a specified position.

js function drawCircle(

) nodejs function drawCircle(

) php function drawCircle(

) cpp m int drawCircle( int

, int

)

-(int) drawCircle : (int)

: (int)

pas vb cs java py cmd function drawCircle(

: LongInt,

: LongInt): LongInt function drawCircle( ) As Integer int drawCircle( int

, int

) int drawCircle( int

, int

) def drawCircle(

)

YDisplay

target

[-layer

layerId

] drawCircle

x y r

Parameters : x

the distance from left of layer to the center of the circle, in pixels

the distance from top of layer to the center of the circle, in pixels

the radius of the circle, in pixels

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

21. High-level API Reference

YDisplayLayer

www.yoctopuce.com

251

21. High-level API Reference

displaylayer

→

drawDisc()

Draws a filled disc at a given position.

js function drawDisc(

) nodejs function drawDisc(

) php function drawDisc(

) cpp m int drawDisc( int

, int

)

-(int) drawDisc : (int)

: (int)

pas vb cs java py cmd function drawDisc(

: LongInt,

: LongInt): LongInt function drawDisc( ) As Integer int drawDisc( int

, int

) int drawDisc( int

, int

) def drawDisc(

)

YDisplay

target

[-layer

layerId

] drawDisc

x y r

Parameters : x

the distance from left of layer to the center of the disc, in pixels

the distance from top of layer to the center of the disc, in pixels

the radius of the disc, in pixels

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

YDisplayLayer

252 www.yoctopuce.com

21. High-level API Reference

displaylayer

→

drawImage() YDisplayLayer

Draws a GIF image at the specified position.

js function drawImage(

imagename

) nodejs function drawImage(

imagename

) php function drawImage(

$imagename

) cpp m int drawImage( int

, int

, string

imagename

)

-(int) drawImage : (int)

: (int)

: (NSString*)

imagename

pas vb cs java py cmd function drawImage(

: LongInt,

imagename

: string): LongInt function drawImage( ) As Integer int drawImage( int

, int

, string

imagename

) int drawImage( int

, int

, String

imagename

) def drawImage(

imagename

)

YDisplay

target

[-layer

layerId

] drawImage

x y imagename

The GIF image must have been previously uploaded to the device built-in memory. If you experience problems using an image file, check the device logs for any error message such as missing image file or bad image file format.

Parameters : x y

the distance from left of layer to the left of the image, in pixels the distance from top of layer to the top of the image, in pixels

imagename

the GIF file name

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

253

21. High-level API Reference

displaylayer

→

drawPixel()

Draws a single pixel at the specified position.

js function drawPixel(

) nodejs function drawPixel(

) php function drawPixel(

) cpp m int drawPixel( int

, int

)

-(int) drawPixel : (int)

: (int)

pas vb cs java py cmd function drawPixel(

: LongInt,

: LongInt): LongInt function drawPixel( ) As Integer int drawPixel( int

, int

) int drawPixel( int

, int

) def drawPixel(

)

YDisplay

target

[-layer

layerId

] drawPixel

x y

Parameters : x

the distance from left of layer, in pixels

the distance from top of layer, in pixels

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

YDisplayLayer

254 www.yoctopuce.com

displaylayer

→

drawRect()

Draws an empty rectangle at a specified position.

js cpp m function drawRect(

) nodejs function drawRect(

) php function drawRect(

$x1

$y1

$x2

$y2

) int drawRect( int

, int

)

-(int) drawRect : (int)

: (int)

pas function drawRect(

: LongInt,

: LongInt): LongInt vb cs java py cmd function drawRect( ) As Integer int drawRect( int

, int

) int drawRect( int

, int

) def drawRect(

)

YDisplay

target

[-layer

layerId

] drawRect

x1 y1 x2 y2

Parameters : x1

the distance from left of layer to the left border of the rectangle, in pixels

the distance from top of layer to the top border of the rectangle, in pixels

the distance from left of layer to the right border of the rectangle, in pixels

the distance from top of layer to the bottom border of the rectangle, in pixels

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

21. High-level API Reference

YDisplayLayer

www.yoctopuce.com

255

21. High-level API Reference

displaylayer

→

drawText() YDisplayLayer

Draws a text string at the specified position.

js function drawText(

anchor

text

) nodejs function drawText(

anchor

text

) php function drawText(

$anchor

$text

) cpp m int drawText( int

, int

, Y_ALIGN

anchor

, string

text

)

-(int) drawText : (int)

: (int)

: (Y_ALIGN)

: (NSString*)

anchor text

pas function drawText(

: LongInt,

anchor

: TYALIGN,

text

: string): LongInt vb cs java py cmd function drawText( ) As Integer int drawText( int

, int

, ALIGN

anchor

, string

text

) int drawText( int

, int

, ALIGN

anchor

, String

text

) def drawText(

anchor

text

)

YDisplay

target

[-layer

layerId

] drawText

x y anchor text

The point of the text that is aligned to the specified pixel position is called the anchor point, and can be chosen among several options. Text is rendered from left to right, without implicit wrapping.

Parameters : x

the distance from left of layer to the text ancor point, in pixels

the distance from top of layer to the text ancor point, in pixels

anchor

the text anchor point, chosen among the

Y_ALIGN

enumeration:

Y_ALIGN_TOP_LEFT

Y_ALIGN_CENTER_LEFT

Y_ALIGN_BASELINE_LEFT

Y_ALIGN_BOTTOM_LEFT

Y_ALIGN_TOP_CENTER , Y_ALIGN_CENTER , Y_ALIGN_BASELINE_CENTER ,

Y _ A L I G N _ B O T T O M _ C E N T E R , Y _ A L I G N _ T O P _ D E C I M A L ,

Y _ A L I G N _ C E N T E R _ D E C I M A L

Y _ A L I G N _ B A S E L I N E _ D E C I M A L

Y_ALIGN_BOTTOM_DECIMAL

Y_ALIGN_TOP_RIGHT

Y_ALIGN_CENTER_RIGHT

Y_ALIGN_BASELINE_RIGHT , Y_ALIGN_BOTTOM_RIGHT .

text

the text string to draw

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

256 www.yoctopuce.com

displaylayer

→

get_display() displaylayer

→

display()

Gets parent YDisplay.

js nodejs function get_display( ) function get_display( ) php cpp function get_display( )

YDisplay* get_display( ) m pas vb cs java py

-(YDisplay*) display function get_display( ): TYDisplay function get_display( ) As YDisplay

YDisplay get_display( )

YDisplay get_display( ) def get_display( )

Returns the parent YDisplay object of the current YDisplayLayer.

Returns :

an YDisplay object

21. High-level API Reference

YDisplayLayer

www.yoctopuce.com

257

21. High-level API Reference

displaylayer

→

get_displayHeight() displaylayer

→

displayHeight()

Returns the display height, in pixels.

js function get_displayHeight( ) nodejs function get_displayHeight( ) php cpp m pas function get_displayHeight( ) int get_displayHeight( )

-(int) displayHeight function get_displayHeight( ): LongInt vb cs java py cmd function get_displayHeight( ) As Integer int get_displayHeight( ) int get_displayHeight( ) def get_displayHeight( )

YDisplay

target

[-layer

layerId

] get_displayHeight

YDisplayLayer

Returns :

an integer corresponding to the display height, in pixels On failure, throws an exception or returns

Y_DISPLAYHEIGHT_INVALID.

258 www.yoctopuce.com

displaylayer

→

get_displayWidth() displaylayer

→

displayWidth()

Returns the display width, in pixels.

js nodejs function get_displayWidth( ) function get_displayWidth( ) php cpp function get_displayWidth( ) int get_displayWidth( ) m pas vb cs

-(int) displayWidth function get_displayWidth( ): LongInt function get_displayWidth( ) As Integer int get_displayWidth( ) java py cmd int get_displayWidth( ) def get_displayWidth( )

YDisplay

target

[-layer

layerId

] get_displayWidth

21. High-level API Reference

YDisplayLayer

Returns :

an integer corresponding to the display width, in pixels On failure, throws an exception or returns

Y_DISPLAYWIDTH_INVALID.

www.yoctopuce.com

259

21. High-level API Reference

displaylayer

→

get_layerHeight() displaylayer

→

layerHeight()

Returns the height of the layers to draw on, in pixels.

js function get_layerHeight( ) nodejs function get_layerHeight( ) php cpp m pas function get_layerHeight( ) int get_layerHeight( )

-(int) layerHeight function get_layerHeight( ): LongInt vb cs java py cmd function get_layerHeight( ) As Integer int get_layerHeight( ) int get_layerHeight( ) def get_layerHeight( )

YDisplay

target

[-layer

layerId

] get_layerHeight

Returns :

an integer corresponding to the height of the layers to draw on, in pixels

On failure, throws an exception or returns Y_LAYERHEIGHT_INVALID.

YDisplayLayer

260 www.yoctopuce.com

displaylayer

→

get_layerWidth() displaylayer

→

layerWidth()

Returns the width of the layers to draw on, in pixels.

js nodejs function get_layerWidth( ) function get_layerWidth( ) php cpp function get_layerWidth( ) int get_layerWidth( ) m pas vb cs

-(int) layerWidth function get_layerWidth( ): LongInt function get_layerWidth( ) As Integer int get_layerWidth( ) java py cmd int get_layerWidth( ) def get_layerWidth( )

YDisplay

target

[-layer

layerId

] get_layerWidth

Returns :

an integer corresponding to the width of the layers to draw on, in pixels

On failure, throws an exception or returns Y_LAYERWIDTH_INVALID.

21. High-level API Reference

YDisplayLayer

www.yoctopuce.com

261

21. High-level API Reference

displaylayer

→

hide() YDisplayLayer

Hides the layer.

js function hide( ) nodejs function hide( ) php function hide( ) cpp m pas vb cs java py cmd int hide( )

-(int) hide function hide( ): LongInt function hide( ) As Integer int hide( ) int hide( ) def hide( )

YDisplay

target

[-layer

layerId

] hide

The state of the layer is perserved but the layer is not displayed on the screen until the next call to unhide()

. Hiding the layer can positively affect the drawing speed, since it postpones the rendering until all operations are completed (double-buffering).

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

262 www.yoctopuce.com

21. High-level API Reference

displaylayer

→

lineTo() YDisplayLayer

Draws a line from current drawing pointer position to the specified position.

js cpp m function lineTo(

) nodejs function lineTo(

) php function lineTo(

) int lineTo( int

, int

)

-(int) lineTo : (int)

: (int)

pas vb cs java py cmd function lineTo(

: LongInt,

: LongInt): LongInt function lineTo( ) As Integer int lineTo( int

, int

) int lineTo( int

, int

) def lineTo(

)

YDisplay

target

[-layer

layerId

] lineTo

x y

The specified destination pixel is included in the line. The pointer position is then moved to the end point of the line.

Parameters : x

the distance from left of layer to the end point of the line, in pixels

the distance from top of layer to the end point of the line, in pixels

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

263

21. High-level API Reference

displaylayer

→

moveTo()

Moves the drawing pointer of this layer to the specified position.

js function moveTo(

) nodejs function moveTo(

) php function moveTo(

) cpp m int moveTo( int

, int

)

-(int) moveTo : (int)

: (int)

pas vb cs java py cmd function moveTo(

: LongInt,

: LongInt): LongInt function moveTo( ) As Integer int moveTo( int

, int

) int moveTo( int

, int

) def moveTo(

)

YDisplay

target

[-layer

layerId

] moveTo

x y

Parameters : x

the distance from left of layer, in pixels

the distance from top of layer, in pixels

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

YDisplayLayer

264 www.yoctopuce.com

21. High-level API Reference

displaylayer

→

reset() YDisplayLayer

Reverts the layer to its initial state (fully transparent, default settings).

js function reset( ) nodejs function reset( ) php function reset( ) cpp m pas vb cs java py cmd int reset( )

-(int) reset function reset( ): LongInt function reset( ) As Integer int reset( ) int reset( ) def reset( )

YDisplay

target

[-layer

layerId

] reset

Reinitializes the drawing pointer to the upper left position, and selects the most visible pen color. If you only want to erase the layer content, use the method clear()

instead.

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

displaylayer

→

selectColorPen() YDisplayLayer

Selects the pen color for all subsequent drawing functions, including text drawing.

js function selectColorPen(

color

) nodejs function selectColorPen(

color

) php function selectColorPen(

$color

) cpp m pas vb cs java py cmd int selectColorPen( int

color

)

-(int) selectColorPen : (int)

color

function selectColorPen(

color

: LongInt): LongInt function selectColorPen( ) As Integer int selectColorPen( int

color

) int selectColorPen( int

color

) def selectColorPen(

color

)

YDisplay

target

[-layer

layerId

] selectColorPen

color

The pen color is provided as an RGB value. For grayscale or monochrome displays, the value is automatically converted to the proper range.

Parameters : color

the desired pen color, as a 24-bit RGB value

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

displaylayer

→

selectEraser() YDisplayLayer

Selects an eraser instead of a pen for all subsequent drawing functions, except for text drawing and bitmap copy functions.

js function selectEraser( ) nodejs function selectEraser( ) php function selectEraser( ) cpp m pas vb cs java py cmd int selectEraser( )

-(int) selectEraser function selectEraser( ): LongInt function selectEraser( ) As Integer int selectEraser( ) int selectEraser( ) def selectEraser( )

YDisplay

target

[-layer

layerId

] selectEraser

Any point drawn using the eraser becomes transparent (as when the layer is empty), showing the other layers beneath it.

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

267

21. High-level API Reference

displaylayer

→

selectFont() YDisplayLayer

Selects a font to use for the next text drawing functions, by providing the name of the font file.

js function selectFont(

fontname

) nodejs function selectFont(

fontname

) php function selectFont(

$fontname

) cpp m pas vb cs java py cmd int selectFont( string

fontname

)

-(int) selectFont : (NSString*)

fontname

function selectFont(

fontname

: string): LongInt function selectFont( ) As Integer int selectFont( string

fontname

) int selectFont( String

fontname

) def selectFont(

fontname

)

YDisplay

target

[-layer

layerId

] selectFont

fontname

You can use a built-in font as well as a font file that you have previously uploaded to the device built-in memory. If you experience problems selecting a font file, check the device logs for any error message such as missing font file or bad font file format.

Parameters : fontname

the font file name

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

displaylayer

→

selectGrayPen() YDisplayLayer

Selects the pen gray level for all subsequent drawing functions, including text drawing.

js function selectGrayPen(

graylevel

) nodejs function selectGrayPen(

graylevel

) php function selectGrayPen(

$graylevel

) cpp m pas vb cs java py cmd int selectGrayPen( int

graylevel

)

-(int) selectGrayPen : (int)

graylevel

function selectGrayPen(

graylevel

: LongInt): LongInt function selectGrayPen( ) As Integer int selectGrayPen( int

graylevel

) int selectGrayPen( int

graylevel

) def selectGrayPen(

graylevel

)

YDisplay

target

[-layer

layerId

] selectGrayPen

graylevel

The gray level is provided as a number between 0 (black) and 255 (white, or whichever the lighest color is). For monochrome displays (without gray levels), any value lower than 128 is rendered as black, and any value equal or above to 128 is non-black.

Parameters : graylevel

the desired gray level, from 0 to 255

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

269

21. High-level API Reference

displaylayer

→

setAntialiasingMode() YDisplayLayer

Enables or disables anti-aliasing for drawing oblique lines and circles.

js function setAntialiasingMode(

mode

) nodejs function setAntialiasingMode(

mode

) php function setAntialiasingMode(

$mode

) cpp m pas vb cs java py cmd int setAntialiasingMode( bool

mode

)

-(int) setAntialiasingMode : (bool)

mode

function setAntialiasingMode(

mode

: boolean): LongInt function setAntialiasingMode( ) As Integer int setAntialiasingMode( bool

mode

) int setAntialiasingMode( boolean

mode

) def setAntialiasingMode(

mode

)

YDisplay

target

[-layer

layerId

] setAntialiasingMode

mode

Anti-aliasing provides a smoother aspect when looked from far enough, but it can add fuzzyness when the display is looked from very close. At the end of the day, it is your personal choice. Anti-aliasing is enabled by default on grayscale and color displays, but you can disable it if you prefer. This setting has no effect on monochrome displays.

Parameters : mode

true to enable antialiasing, false to disable it.

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

270 www.yoctopuce.com

21. High-level API Reference

displaylayer

→

setConsoleBackground() YDisplayLayer

Sets up the background color used by the clearConsole

function and by the console scrolling feature.

js nodejs function setConsoleBackground(

bgcol

) function setConsoleBackground(

bgcol

) php cpp function setConsoleBackground(

$bgcol

) int setConsoleBackground( int

bgcol

) m pas vb cs

-(int) setConsoleBackground : (int)

bgcol

function setConsoleBackground(

bgcol

: LongInt): LongInt function setConsoleBackground( ) As Integer int setConsoleBackground( int

bgcol

) java py cmd int setConsoleBackground( int

bgcol

) def setConsoleBackground(

bgcol

)

YDisplay

target

[-layer

layerId

] setConsoleBackground

bgcol

Parameters : bgcol

the background gray level to use when scrolling (0 = black, 255 = white), or -1 for transparent

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

271

21. High-level API Reference

displaylayer

→

setConsoleMargins()

Sets up display margins for the consoleOut

function.

js function setConsoleMargins(

) nodejs function setConsoleMargins(

) php cpp m function setConsoleMargins(

$x1

$y1

$x2

$y2

) int setConsoleMargins( int

, int

)

-(int) setConsoleMargins : (int)

: (int)

pas function setConsoleMargins(

: LongInt,

x2 y2

: LongInt,

: LongInt): LongInt vb cs java py cmd function setConsoleMargins( ) As Integer int setConsoleMargins( int

, int

) int setConsoleMargins( int

, int

) def setConsoleMargins(

)

YDisplay

target

[-layer

layerId

] setConsoleMargins

x1 y1 x2 y2

Parameters : x1

the distance from left of layer to the left margin, in pixels

the distance from top of layer to the top margin, in pixels

the distance from left of layer to the right margin, in pixels

the distance from top of layer to the bottom margin, in pixels

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

YDisplayLayer

272 www.yoctopuce.com

displaylayer

→

setConsoleWordWrap()

Sets up the wrapping behaviour used by the consoleOut

function.

js nodejs function setConsoleWordWrap(

wordwrap

) function setConsoleWordWrap(

wordwrap

) php cpp function setConsoleWordWrap(

$wordwrap

) int setConsoleWordWrap( bool

wordwrap

) m pas vb cs

-(int) setConsoleWordWrap : (bool)

wordwrap

function setConsoleWordWrap(

wordwrap

: boolean): LongInt function setConsoleWordWrap( ) As Integer int setConsoleWordWrap( bool

wordwrap

) java py cmd int setConsoleWordWrap( boolean

wordwrap

) def setConsoleWordWrap(

wordwrap

)

YDisplay

target

[-layer

layerId

] setConsoleWordWrap

wordwrap

21. High-level API Reference

YDisplayLayer

Parameters : wordwrap

true

to wrap only between words, false

to wrap on the last column anyway.

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

273

21. High-level API Reference

displaylayer

→

setLayerPosition() YDisplayLayer

Sets the position of the layer relative to the display upper left corner.

js function setLayerPosition(

scrollTime

) nodejs function setLayerPosition(

scrollTime

) php function setLayerPosition(

$scrollTime

) cpp m int setLayerPosition( int

, int

scrollTime

)

-(int) setLayerPosition : (int)

: (int)

scrollTime

pas function setLayerPosition(

: LongInt,

scrollTime

: LongInt): LongInt vb cs java py cmd function setLayerPosition( ) As Integer int setLayerPosition( int

, int

scrollTime

) int setLayerPosition( int

, int

scrollTime

) def setLayerPosition(

scrollTime

)

YDisplay

target

[-layer

layerId

] setLayerPosition

x y scrollTime

When smooth scrolling is used, the display offset of the layer is automatically updated during the next milliseconds to animate the move of the layer.

Parameters : x

the distance from left of display to the upper left corner of the layer

the distance from top of display to the upper left corner of the layer

scrollTime

number of milliseconds to use for smooth scrolling, or 0 if the scrolling should be immediate.

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

274 www.yoctopuce.com

displaylayer

→

unhide()

Shows the layer.

js function unhide( ) nodejs function unhide( ) php function unhide( ) cpp m pas vb cs java py cmd int unhide( )

-(int) unhide function unhide( ): LongInt function unhide( ) As Integer int unhide( ) int unhide( ) def unhide( )

YDisplay

target

[-layer

layerId

] unhide

Shows the layer again after a hide command.

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

21. High-level API Reference

YDisplayLayer

www.yoctopuce.com

275

21. High-level API Reference

21.5. AnButton function interface

In order to use the functions described here, you should include: js nodejs php cpp m

#include "yocto_anbutton.h"

#import "yocto_anbutton.h" pas vb cs java py uses yocto_anbutton; yocto_anbutton.vb

yocto_anbutton.cs

import com.yoctopuce.YoctoAPI.YAnButton; from yocto_anbutton import *

Global functions

yFindAnButton(

func

)

Retrieves an analog input for a given identifier.

yFirstAnButton()

Starts the enumeration of analog inputs currently accessible.

YAnButton

methods

anbutton

Returns a short text that describes the analog input in the form

TYPE(NAME)=SERIAL.FUNCTIONID

anbutton

get_advertisedValue()

Returns the current value of the analog input (no more than 6 characters).

anbutton

get_analogCalibration()

Tells if a calibration process is currently ongoing.

anbutton

get_calibratedValue()

Returns the current calibrated input value (between 0 and 1000, included).

anbutton

get_calibrationMax()

Returns the maximal value measured during the calibration (between 0 and 4095, included).

anbutton

get_calibrationMin()

Returns the minimal value measured during the calibration (between 0 and 4095, included).

anbutton

Returns the error message of the latest error with the analog input.

anbutton

Returns the numerical error code of the latest error with the analog input.

anbutton

get_friendlyName()

Returns a global identifier of the analog input in the format MODULE_NAME.FUNCTION_NAME

anbutton

get_functionDescriptor()

Returns a unique identifier of type YFUN_DESCR corresponding to the function.

anbutton

get_functionId()

276 www.yoctopuce.com

21. High-level API Reference

Returns the hardware identifier of the analog input, without reference to the module.

anbutton

Returns the unique hardware identifier of the analog input in the form SERIAL.FUNCTIONID

anbutton

get_isPressed()

Returns true if the input (considered as binary) is active (closed contact), and false otherwise.

anbutton

get_lastTimePressed()

Returns the number of elapsed milliseconds between the module power on and the last time the input button was pressed (the input contact transitionned from open to closed).

anbutton

get_lastTimeReleased()

Returns the number of elapsed milliseconds between the module power on and the last time the input button was released (the input contact transitionned from closed to open).

anbutton

Returns the logical name of the analog input.

anbutton

get_module()

Gets the

YModule

object for the device on which the function is located.

anbutton

get_module_async(

callback

context

)

Gets the

YModule

object for the device on which the function is located (asynchronous version).

anbutton

get_pulseCounter()

Returns the pulse counter value

anbutton

get_pulseTimer()

Returns the timer of the pulses counter (ms)

anbutton

get_rawValue()

Returns the current measured input value as-is (between 0 and 4095, included).

anbutton

get_sensitivity()

Returns the sensibility for the input (between 1 and 1000) for triggering user callbacks.

anbutton

Returns the value of the userData attribute, as previously stored using method set_userData .

anbutton

Checks if the analog input is currently reachable, without raising any error.

anbutton

callback

context

)

Checks if the analog input is currently reachable, without raising any error (asynchronous version).

anbutton

msValidity

)

Preloads the analog input cache with a specified validity duration.

anbutton

msValidity

callback

context

)

Preloads the analog input cache with a specified validity duration (asynchronous version).

anbutton

nextAnButton()

Continues the enumeration of analog inputs started using yFirstAnButton() .

anbutton

registerValueCallback(

callback

)

Registers the callback function that is invoked on every change of advertised value.

anbutton

resetCounter()

Returns the pulse counter value as well as his timer

anbutton

set_analogCalibration(

newval

)

Starts or stops the calibration process.

anbutton

set_calibrationMax(

newval

)

Changes the maximal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration.

www.yoctopuce.com

277

21. High-level API Reference

anbutton

set_calibrationMin(

newval

)

Changes the minimal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration.

anbutton

newval

)

Changes the logical name of the analog input.

anbutton

set_sensitivity(

newval

)

Changes the sensibility for the input (between 1 and 1000) for triggering user callbacks.

anbutton

data

)

Stores a user context provided as argument in the userData attribute of the function.

anbutton

callback

context

)

Waits for all pending asynchronous commands on the module to complete, and invoke the user-provided callback function.

278 www.yoctopuce.com

YAnButton.FindAnButton() yFindAnButton()

Retrieves an analog input for a given identifier.

js nodejs function yFindAnButton(

func

) function FindAnButton(

func

) php cpp function yFindAnButton(

$func

)

YAnButton* yFindAnButton( const string&

func

) m pas vb cs java py

YAnButton* yFindAnButton( NSString*

func

) function yFindAnButton(

func

: string): TYAnButton function yFindAnButton( ByVal

func

As String) As YAnButton

YAnButton FindAnButton( string

func

)

YAnButton FindAnButton( String

func

) def FindAnButton(

func

)

The identifier can be specified using several formats:

21. High-level API Reference

YAnButton

●

FunctionLogicalName

ModuleSerialNumber.FunctionIdentifier

ModuleSerialNumber.FunctionLogicalName

ModuleLogicalName.FunctionIdentifier

ModuleLogicalName.FunctionLogicalName

This function does not require that the analog input is online at the time it is invoked. The returned object is nevertheless valid. Use the method YAnButton.isOnline() to test if the analog input is indeed online at a given time. In case of ambiguity when looking for an analog input by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.

Parameters : func

a string that uniquely characterizes the analog input

Returns :

YAnButton

object allowing you to drive the analog input.

www.yoctopuce.com

279

21. High-level API Reference

YAnButton.FirstAnButton() yFirstAnButton()

Starts the enumeration of analog inputs currently accessible.

js function yFirstAnButton( ) nodejs function FirstAnButton( ) php cpp m pas function yFirstAnButton( )

YAnButton* yFirstAnButton( )

YAnButton* yFirstAnButton( ) function yFirstAnButton( ): TYAnButton vb cs java py function yFirstAnButton( ) As YAnButton

YAnButton FirstAnButton( )

YAnButton FirstAnButton( ) def FirstAnButton( )

Use the method

YAnButton.nextAnButton()

to iterate on next analog inputs.

YAnButton

Returns :

a pointer to a YAnButton object, corresponding to the first analog input currently online, or a null pointer if there are none.

280 www.yoctopuce.com

21. High-level API Reference

anbutton

→

describe() YAnButton

R e t u r n s a s h o r t t e x t t h a t d e s c r i b e s t h e a n a l o g i n p u t i n t h e f o r m

T Y P E ( N A M E ) = S E R I A L . F U N C T I O N I D

js nodejs function describe( ) function describe( ) php cpp function describe( ) string describe( ) m pas vb cs java py

-(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.relay1)=RELAYLO1-123456.relay1

if the module is already connected or

Relay(BadCustomeName.relay1)=unresolved

if the module has not yet been connected. This method does not trigger any USB or TCP transaction and can therefore be used in a debugger.

Returns :

a string that describes the analog input (ex:

Relay(MyCustomName.relay1)=RELAYLO1-

123456.relay1

)

www.yoctopuce.com

281

21. High-level API Reference

anbutton

→

get_advertisedValue() anbutton

→

advertisedValue()

Returns the current value of the analog input (no more than 6 characters).

js function get_advertisedValue( ) nodejs function get_advertisedValue( ) php cpp m pas function get_advertisedValue( ) string get_advertisedValue( )

-(NSString*) advertisedValue function get_advertisedValue( ): string vb cs java py cmd function get_advertisedValue( ) As String string get_advertisedValue( )

String get_advertisedValue( ) def get_advertisedValue( )

YAnButton

target

get_advertisedValue

YAnButton

Returns :

a string corresponding to the current value of the analog input (no more than 6 characters). On failure, throws an exception or returns

Y_ADVERTISEDVALUE_INVALID

282 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_analogCalibration() anbutton

→

analogCalibration()

Tells if a calibration process is currently ongoing.

js nodejs function get_analogCalibration( ) function get_analogCalibration( ) php cpp function get_analogCalibration( )

Y_ANALOGCALIBRATION_enum get_analogCalibration( ) m pas vb cs

-(Y_ANALOGCALIBRATION_enum) analogCalibration function get_analogCalibration( ): Integer function get_analogCalibration( ) As Integer int get_analogCalibration( ) java py cmd int get_analogCalibration( ) def get_analogCalibration( )

YAnButton

target

get_analogCalibration

Returns :

either Y_ANALOGCALIBRATION_OFF or Y_ANALOGCALIBRATION_ON

On failure, throws an exception or returns

Y_ANALOGCALIBRATION_INVALID

YAnButton

www.yoctopuce.com

283

21. High-level API Reference

anbutton

→

get_calibratedValue() anbutton

→

calibratedValue()

Returns the current calibrated input value (between 0 and 1000, included).

js function get_calibratedValue( ) nodejs function get_calibratedValue( ) php cpp m pas function get_calibratedValue( ) int get_calibratedValue( )

-(int) calibratedValue function get_calibratedValue( ): LongInt vb cs java py cmd function get_calibratedValue( ) As Integer int get_calibratedValue( ) int get_calibratedValue( ) def get_calibratedValue( )

YAnButton

target

get_calibratedValue

Returns :

an integer corresponding to the current calibrated input value (between 0 and 1000, included)

On failure, throws an exception or returns Y_CALIBRATEDVALUE_INVALID .

YAnButton

284 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_calibrationMax() anbutton

→

calibrationMax()

YAnButton

Returns the maximal value measured during the calibration (between 0 and 4095, included).

js nodejs function get_calibrationMax( ) function get_calibrationMax( ) php cpp function get_calibrationMax( ) int get_calibrationMax( ) m pas vb cs

-(int) calibrationMax function get_calibrationMax( ): LongInt function get_calibrationMax( ) As Integer int get_calibrationMax( ) java py cmd int get_calibrationMax( ) def get_calibrationMax( )

YAnButton

target

get_calibrationMax

Returns :

an integer corresponding to the maximal value measured during the calibration (between 0 and 4095, included)

On failure, throws an exception or returns

Y_CALIBRATIONMAX_INVALID

www.yoctopuce.com

285

21. High-level API Reference

anbutton

→

get_calibrationMin() anbutton

→

calibrationMin()

YAnButton

Returns the minimal value measured during the calibration (between 0 and 4095, included).

js function get_calibrationMin( ) nodejs function get_calibrationMin( ) php cpp m pas function get_calibrationMin( ) int get_calibrationMin( )

-(int) calibrationMin function get_calibrationMin( ): LongInt vb cs java py cmd function get_calibrationMin( ) As Integer int get_calibrationMin( ) int get_calibrationMin( ) def get_calibrationMin( )

YAnButton

target

get_calibrationMin

Returns :

an integer corresponding to the minimal value measured during the calibration (between 0 and 4095, included)

On failure, throws an exception or returns

Y_CALIBRATIONMIN_INVALID

286 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_errorMessage() anbutton

→

errorMessage()

Returns the error message of the latest error with the analog input.

js nodejs function get_errorMessage( ) function get_errorMessage( ) php cpp function get_errorMessage( ) string get_errorMessage( ) m pas vb cs java py

-(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.

YAnButton

Returns :

a string corresponding to the latest error message that occured while using the analog input object

www.yoctopuce.com

287

21. High-level API Reference

anbutton

→

get_errorType() anbutton

→

errorType()

Returns the numerical error code of the latest error with the analog input.

js function get_errorType( ) nodejs function get_errorType( ) php cpp pas vb function get_errorType( )

YRETCODE get_errorType( ) function get_errorType( ): YRETCODE function get_errorType( ) As YRETCODE cs java py

YRETCODE get_errorType( ) int get_errorType( ) def get_errorType( )

This method is mostly useful when using the Yoctopuce library with exceptions disabled.

YAnButton

Returns :

a number corresponding to the code of the latest error that occured while using the analog input object

288 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_friendlyName() anbutton

→

friendlyName()

YAnButton

Returns a global identifier of the analog input in the format

MODULE_NAME.FUNCTION_NAME

js function get_friendlyName( ) nodejs function get_friendlyName( ) php function get_friendlyName( ) cpp m cs java py 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 analog input if they are defined, otherwise the serial number of the module and the hardware identifier of the analog input (for exemple:

MyCustomName.relay1

)

Returns :

a string that uniquely identifies the analog input using logical names (ex: MyCustomName.relay1

) On failure, throws an exception or returns

Y_FRIENDLYNAME_INVALID

www.yoctopuce.com

289

21. High-level API Reference

anbutton

→

get_functionDescriptor() anbutton

→

functionDescriptor()

YAnButton

Returns a unique identifier of type

YFUN_DESCR

corresponding to the function.

js function get_functionDescriptor( ) nodejs function get_functionDescriptor( ) php function get_functionDescriptor( ) cpp m pas vb cs java py

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

290 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_functionId() anbutton

→

functionId()

Returns the hardware identifier of the analog input, without reference to the module.

js nodejs function get_functionId( ) function get_functionId( ) php cpp function get_functionId( ) string get_functionId( ) m vb cs java py

-(NSString*) functionId function get_functionId( ) As String string get_functionId( )

String get_functionId( ) def get_functionId( )

YAnButton

For example relay1

Returns :

a string that identifies the analog input (ex: relay1 ) On failure, throws an exception or returns

Y_FUNCTIONID_INVALID

www.yoctopuce.com

291

21. High-level API Reference

anbutton

→

get_hardwareId() anbutton

→

hardwareId()

YAnButton

Returns the unique hardware identifier of the analog input in the form

SERIAL.FUNCTIONID

js function get_hardwareId( ) nodejs function get_hardwareId( ) php function get_hardwareId( ) cpp m vb cs java py string get_hardwareId( )

-(NSString*) hardwareId function get_hardwareId( ) As String string get_hardwareId( )

String get_hardwareId( ) def get_hardwareId( )

The unique hardware identifier is composed of the device serial number and of the hardware identifier of the analog input. (for example

RELAYLO1-123456.relay1

)

Returns :

a string that uniquely identifies the analog input (ex:

RELAYLO1-123456.relay1

) On failure, throws an exception or returns Y_HARDWAREID_INVALID .

292 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_isPressed() anbutton

→

isPressed()

YAnButton

Returns true if the input (considered as binary) is active (closed contact), and false otherwise.

js nodejs function get_isPressed( ) function get_isPressed( ) php cpp function get_isPressed( )

Y_ISPRESSED_enum get_isPressed( ) m pas vb cs

-(Y_ISPRESSED_enum) isPressed function get_isPressed( ): Integer function get_isPressed( ) As Integer int get_isPressed( ) java py cmd int get_isPressed( ) def get_isPressed( )

YAnButton

target

get_isPressed

Returns :

either Y_ISPRESSED_FALSE or Y_ISPRESSED_TRUE , according to true if the input (considered as binary) is active (closed contact), and false otherwise

On failure, throws an exception or returns

Y_ISPRESSED_INVALID

www.yoctopuce.com

293

21. High-level API Reference

anbutton

→

get_lastTimePressed() anbutton

→

lastTimePressed()

YAnButton

Returns the number of elapsed milliseconds between the module power on and the last time the input button was pressed (the input contact transitionned from open to closed).

js function get_lastTimePressed( ) nodejs function get_lastTimePressed( ) php cpp m pas function get_lastTimePressed( ) s64 get_lastTimePressed( )

-(s64) lastTimePressed function get_lastTimePressed( ): int64 vb cs java py cmd function get_lastTimePressed( ) As Long long get_lastTimePressed( ) long get_lastTimePressed( ) def get_lastTimePressed( )

YAnButton

target

get_lastTimePressed

Returns :

an integer corresponding to the number of elapsed milliseconds between the module power on and the last time the input button was pressed (the input contact transitionned from open to closed)

On failure, throws an exception or returns

Y_LASTTIMEPRESSED_INVALID

294 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_lastTimeReleased() anbutton

→

lastTimeReleased()

YAnButton

Returns the number of elapsed milliseconds between the module power on and the last time the input button was released (the input contact transitionned from closed to open).

js nodejs function get_lastTimeReleased( ) function get_lastTimeReleased( ) php cpp function get_lastTimeReleased( ) s64 get_lastTimeReleased( ) m pas vb cs

-(s64) lastTimeReleased function get_lastTimeReleased( ): int64 function get_lastTimeReleased( ) As Long long get_lastTimeReleased( ) java py cmd long get_lastTimeReleased( ) def get_lastTimeReleased( )

YAnButton

target

get_lastTimeReleased

Returns :

an integer corresponding to the number of elapsed milliseconds between the module power on and the last time the input button was released (the input contact transitionned from closed to open)

On failure, throws an exception or returns

Y_LASTTIMERELEASED_INVALID

www.yoctopuce.com

295

21. High-level API Reference

anbutton

→

get_logicalName() anbutton

→

logicalName()

Returns the logical name of the analog input.

js function get_logicalName( ) nodejs function get_logicalName( ) php cpp m pas function get_logicalName( ) string get_logicalName( )

-(NSString*) logicalName function get_logicalName( ): string vb cs java py cmd function get_logicalName( ) As String string get_logicalName( )

String get_logicalName( ) def get_logicalName( )

YAnButton

target

get_logicalName

YAnButton

Returns :

a string corresponding to the logical name of the analog input. On failure, throws an exception or returns

Y_LOGICALNAME_INVALID

296 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_module() anbutton

→

module()

YAnButton

Gets the

YModule

object for the device on which the function is located.

js function get_module( ) nodejs function get_module( ) php function get_module( ) cpp m pas vb cs java py

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 module, the returned instance of

YModule

is not shown as online.

Returns :

an instance of YModule

www.yoctopuce.com

297

21. High-level API Reference

anbutton

→

get_module_async() anbutton

→

module_async()

YAnButton

Gets the

YModule

object for the device on which the function is located (asynchronous version).

js function get_module_async(

callback

context

) nodejs function get_module_async(

callback

context

)

If the function cannot be located on any module, the returned

YModule

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.

298 www.yoctopuce.com

anbutton

→

get_pulseCounter() anbutton

→

pulseCounter()

Returns the pulse counter value js nodejs function get_pulseCounter( ) function get_pulseCounter( ) php cpp function get_pulseCounter( ) s64 get_pulseCounter( ) m pas vb cs java py

-(s64) pulseCounter function get_pulseCounter( ): int64 function get_pulseCounter( ) As Long long get_pulseCounter( ) long get_pulseCounter( ) def get_pulseCounter( )

Returns :

an integer corresponding to the pulse counter value

On failure, throws an exception or returns

Y_PULSECOUNTER_INVALID

21. High-level API Reference

YAnButton

www.yoctopuce.com

299

21. High-level API Reference

anbutton

→

get_pulseTimer() anbutton

→

pulseTimer()

Returns the timer of the pulses counter (ms) js function get_pulseTimer( ) nodejs function get_pulseTimer( ) php cpp m pas function get_pulseTimer( ) s64 get_pulseTimer( )

-(s64) pulseTimer function get_pulseTimer( ): int64 vb cs java py function get_pulseTimer( ) As Long long get_pulseTimer( ) long get_pulseTimer( ) def get_pulseTimer( )

Returns :

an integer corresponding to the timer of the pulses counter (ms)

On failure, throws an exception or returns

Y_PULSETIMER_INVALID

YAnButton

300 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_rawValue() anbutton

→

rawValue()

Returns the current measured input value as-is (between 0 and 4095, included).

js nodejs function get_rawValue( ) function get_rawValue( ) php cpp function get_rawValue( ) int get_rawValue( ) m pas vb cs

-(int) rawValue function get_rawValue( ): LongInt function get_rawValue( ) As Integer int get_rawValue( ) java py cmd int get_rawValue( ) def get_rawValue( )

YAnButton

target

get_rawValue

YAnButton

Returns :

an integer corresponding to the current measured input value as-is (between 0 and 4095, included)

On failure, throws an exception or returns Y_RAWVALUE_INVALID .

www.yoctopuce.com

301

21. High-level API Reference

anbutton

→

get_sensitivity() anbutton

→

sensitivity()

Returns the sensibility for the input (between 1 and 1000) for triggering user callbacks.

js function get_sensitivity( ) nodejs function get_sensitivity( ) php cpp m pas function get_sensitivity( ) int get_sensitivity( )

-(int) sensitivity function get_sensitivity( ): LongInt vb cs java py cmd function get_sensitivity( ) As Integer int get_sensitivity( ) int get_sensitivity( ) def get_sensitivity( )

YAnButton

target

get_sensitivity

YAnButton

Returns :

an integer corresponding to the sensibility for the input (between 1 and 1000) for triggering user callbacks

On failure, throws an exception or returns Y_SENSITIVITY_INVALID .

302 www.yoctopuce.com

21. High-level API Reference

anbutton

→

get_userData() anbutton

→

userData()

YAnButton

Returns the value of the userData attribute, as previously stored using method set_userData

js function get_userData( ) nodejs function get_userData( ) php function get_userData( ) cpp m pas vb cs java py 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

303

21. High-level API Reference

anbutton

→

isOnline() YAnButton

Checks if the analog input is currently reachable, without raising any error.

js function isOnline( ) nodejs function isOnline( ) php function isOnline( ) cpp m pas vb cs java py 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 analog input in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the analog input.

Returns :

true

if the analog input can be reached, and false

otherwise

304 www.yoctopuce.com

21. High-level API Reference

anbutton

→

isOnline_async() YAnButton

Checks if the analog input is currently reachable, without raising any error (asynchronous version).

js function isOnline_async(

callback

context

) nodejs function isOnline_async(

callback

context

)

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.

www.yoctopuce.com

305

21. High-level API Reference

anbutton

→

load() YAnButton

Preloads the analog input cache with a specified validity duration.

js function load(

msValidity

) nodejs function load(

msValidity

) php function load(

$msValidity

) cpp m pas vb cs java py

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

)

Parameters : msValidity

an integer corresponding to the validity attributed to the loaded function parameters, in milliseconds

Returns :

YAPI_SUCCESS when the call succeeds. On failure, throws an exception or returns a negative error code.

306 www.yoctopuce.com

21. High-level API Reference

anbutton

→

load_async() YAnButton

Preloads the analog input cache with a specified validity duration (asynchronous version).

js function load_async(

msValidity

callback

context

) nodejs function load_async(

msValidity

callback

context

)

Parameters : msValidity

an integer corresponding to the validity of the loaded function parameters, in milliseconds

callback

callback function that is invoked when the result is known. The callback function receives three arguments: the caller-specific context object, the receiving function object and the error code

(or

YAPI_SUCCESS

)

context

caller-specific object that is passed as-is to the callback function

Returns :

nothing : the result is provided to the callback.

www.yoctopuce.com

307

21. High-level API Reference

anbutton

→

nextAnButton()

Continues the enumeration of analog inputs started using yFirstAnButton()

js function nextAnButton( ) nodejs function nextAnButton( ) php cpp m pas function nextAnButton( )

YAnButton * nextAnButton( )

-(YAnButton*) nextAnButton function nextAnButton( ): TYAnButton vb cs java py function nextAnButton( ) As YAnButton

YAnButton nextAnButton( )

YAnButton nextAnButton( ) def nextAnButton( )

YAnButton

Returns :

a pointer to a

YAnButton

object, corresponding to an analog input currently online, or a null

pointer if there are no more analog inputs to enumerate.

308 www.yoctopuce.com

21. High-level API Reference

anbutton

→

registerValueCallback()

Registers the callback function that is invoked on every change of advertised value.

js function registerValueCallback(

callback

) nodejs function registerValueCallback(

callback

) php function registerValueCallback(

$callback

) cpp m pas vb cs java py int registerValueCallback( YAnButtonValueCallback

callback

)

-(int) registerValueCallback : (YAnButtonValueCallback)

callback

function registerValueCallback(

callback

: TYAnButtonValueCallback): LongInt function registerValueCallback( ) As Integer int registerValueCallback( ValueCallback

callback

) int registerValueCallback( UpdateCallback

callback

) def registerValueCallback(

callback

)

YAnButton

The callback is invoked only during the execution of ySleep

or yHandleEvents

Parameters : callback

www.yoctopuce.com

309

21. High-level API Reference

anbutton

→

resetCounter()

Returns the pulse counter value as well as his timer js function resetCounter( ) nodejs function resetCounter( ) php function resetCounter( ) cpp m pas vb cs java py int resetCounter( )

-(int) resetCounter function resetCounter( ): integer function resetCounter( ) As Integer int resetCounter( ) int resetCounter( ) def resetCounter( )

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

YAnButton

310 www.yoctopuce.com

21. High-level API Reference

anbutton

→

set_analogCalibration() anbutton

→

setAnalogCalibration()

Starts or stops the calibration process.

js nodejs function set_analogCalibration(

newval

) function set_analogCalibration(

newval

) php cpp function set_analogCalibration(

$newval

) int set_analogCalibration( Y_ANALOGCALIBRATION_enum

newval

) m pas vb cs

-(int) setAnalogCalibration : (Y_ANALOGCALIBRATION_enum)

newval

function set_analogCalibration(

newval

: Integer): integer function set_analogCalibration( ByVal

newval

As Integer) As Integer int set_analogCalibration( int

newval

) java py cmd int set_analogCalibration( int

newval

) def set_analogCalibration(

newval

)

YAnButton

target

set_analogCalibration

newval

YAnButton

Remember to call the saveToFlash()

method of the module at the end of the calibration if the modification must be kept.

Parameters : newval

either Y_ANALOGCALIBRATION_OFF or Y_ANALOGCALIBRATION_ON

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

311

21. High-level API Reference

anbutton

→

set_calibrationMax() anbutton

→

setCalibrationMax()

YAnButton

Changes the maximal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration.

js function set_calibrationMax(

newval

) nodejs function set_calibrationMax(

newval

) php cpp m pas function set_calibrationMax(

$newval

) int set_calibrationMax( int

newval

)

-(int) setCalibrationMax : (int)

newval

function set_calibrationMax(

newval

: LongInt): integer vb cs java py cmd function set_calibrationMax( ByVal

newval

As Integer) As Integer int set_calibrationMax( int

newval

) int set_calibrationMax( int

newval

) def set_calibrationMax(

newval

)

YAnButton

target

set_calibrationMax

newval

Remember to call the saveToFlash()

method of the module if the modification must be kept.

Parameters : newval

an integer corresponding to the maximal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

312 www.yoctopuce.com

21. High-level API Reference

anbutton

→

set_calibrationMin() anbutton

→

setCalibrationMin()

YAnButton

Changes the minimal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration.

js nodejs function set_calibrationMin(

newval

) function set_calibrationMin(

newval

) php cpp function set_calibrationMin(

$newval

) int set_calibrationMin( int

newval

) m pas vb cs

-(int) setCalibrationMin : (int)

newval

function set_calibrationMin(

newval

: LongInt): integer function set_calibrationMin( ByVal

newval

As Integer) As Integer int set_calibrationMin( int

newval

) java py cmd int set_calibrationMin( int

newval

) def set_calibrationMin(

newval

)

YAnButton

target

set_calibrationMin

newval

Remember to call the saveToFlash()

method of the module if the modification must be kept.

Parameters : newval

an integer corresponding to the minimal calibration value for the input (between 0 and 4095, included), without actually starting the automated calibration

Returns :

YAPI_SUCCESS

if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

313

21. High-level API Reference

anbutton

→

set_logicalName() anbutton

→

setLogicalName()

Changes the logical name of the analog input.

js function set_logicalName(

newval

) nodejs function set_logicalName(

newval

) php cpp m pas function set_logicalName(

$newval

) int set_logicalName( const string&

newval

)

-(int) setLogicalName : (NSString*)

newval

function set_logicalName(

newval

: string): integer vb cs java py cmd function set_logicalName( ByVal

newval

As String) As Integer int set_logicalName( string

newval

) int set_logicalName( String

newval

) def set_logicalName(

newval

)

YAnButton

target

set_logicalName

newval

YAnButton

You can use yCheckLogicalName()

prior to this call to make sure that your parameter is valid.

Remember to call the saveToFlash()

method of the module if the modification must be kept.

Parameters : newval

a string corresponding to the logical name of the analog input.

Returns :

YAPI_SUCCESS if the call succeeds. On failure, throws an exception or returns a negative error code.

314 www.yoctopuce.com

21. High-level API Reference

anbutton

→

set_sensitivity() anbutton

→

setSensitivity()

YAnButton

Changes the sensibility for the input (between 1 and 1000) for triggering user callbacks.

js nodejs function set_sensitivity(

newval

) function set_sensitivity(

newval

) php cpp function set_sensitivity(

$newval

) int set_sensitivity( int

newval

) m pas vb cs

-(int) setSensitivity : (int)

newval

function set_sensitivity(

newval

: LongInt): integer function set_sensitivity( ByVal

newval

As Integer) As Integer int set_sensitivity( int

newval

) java py cmd int set_sensitivity( int

newval

) def set_sensitivity(

newval

)

YAnButton

target

set_sensitivity

newval

The sensibility is used to filter variations around a fixed value, but does not preclude the transmission of events when the input value evolves constantly in the same direction. Special case: when the value

1000 is used, the callback will only be thrown when the logical state of the input switches from pressed to released and back. Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters : newval

an integer corresponding to the sensibility for the input (between 1 and 1000) for triggering user callbacks

Returns :

YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

www.yoctopuce.com

315

21. High-level API Reference

anbutton

→

set_userData() anbutton

→

setUserData()

YAnButton

Stores a user context provided as argument in the userData attribute of the function.

js function set_userData(

data

) nodejs function set_userData(

data

) php cpp m pas function set_userData(

$data

) void set_userData( void*

data

)

-(void) setUserData : (void*)

data

procedure set_userData(

data

: Tobject) vb cs java py 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

316 www.yoctopuce.com

21. High-level API Reference

anbutton

→

wait_async() YAnButton

Waits for all pending asynchronous commands on the module to complete, and invoke the userprovided callback function.

js function wait_async(

callback

context

) nodejs 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

context

caller-specific object that is passed as-is to the callback function

Returns :

nothing.

www.yoctopuce.com

317

21. High-level API Reference

21.6. Files function interface

The filesystem interface makes it possible to store files on some devices, for instance to design a custom web UI (for networked devices) or to add fonts (on display devices).

In order to use the functions described here, you should include: js nodejs php cpp

#include "yocto_files.h" m pas vb cs java py

#import "yocto_files.h" uses yocto_files; yocto_files.vb

yocto_files.cs

import com.yoctopuce.YoctoAPI.YFiles; from yocto_files import *

yFindFiles(

func

)

Retrieves a filesystem for a given identifier.

Global functions

yFirstFiles()

Starts the enumeration of filesystems currently accessible.

YFiles

methods

files

Returns a short text that describes the filesystem in the form TYPE(NAME)=SERIAL.FUNCTIONID

files

download(

pathname

)

Downloads the requested file and returns a binary buffer with its content.

files

download_async(

pathname

callback

context

)

Downloads the requested file and returns a binary buffer with its content.

files

format_fs()

Reinitializes the filesystem to its clean, unfragmented, empty state.

files

get_advertisedValue()

Returns the current value of the filesystem (no more than 6 characters).

files

Returns the error message of the latest error with the filesystem.

files

Returns the numerical error code of the latest error with the filesystem.

files

get_filesCount()

Returns the number of files currently loaded in the filesystem.

files

get_freeSpace()

Returns the free space for uploading new files to the filesystem, in bytes.

files

get_friendlyName()

Returns a global identifier of the filesystem in the format MODULE_NAME.FUNCTION_NAME

files

get_functionDescriptor()

Returns a unique identifier of type YFUN_DESCR corresponding to the function.

files

get_functionId()

318 www.yoctopuce.com

21. High-level API Reference

Returns the hardware identifier of the filesystem, without reference to the module.

files

Returns the unique hardware identifier of the filesystem in the form SERIAL.FUNCTIONID

files

get_list(

pattern

)

Returns a list of YFileRecord objects that describe files currently loaded in the filesystem.

files

Returns the logical name of the filesystem.

files

get_module()

Gets the YModule object for the device on which the function is located.

files

get_module_async(

callback

context

)

Gets the YModule object for the device on which the function is located (asynchronous version).

files

Returns the value of the userData attribute, as previously stored using method set_userData .

files

Checks if the filesystem is currently reachable, without raising any error.

files

callback

context

)

Checks if the filesystem is currently reachable, without raising any error (asynchronous version).

files

msValidity

)

Preloads the filesystem cache with a specified validity duration.

files

msValidity

callback

context

)

Preloads the filesystem cache with a specified validity duration (asynchronous version).

files

nextFiles()

Continues the enumeration of filesystems started using yFirstFiles()

files

registerValueCallback(

callback

)

Registers the callback function that is invoked on every change of advertised value.

files

remove(

pathname

)

Deletes a file, given by its full path name, from the filesystem.

files

newval

)

Changes the logical name of the filesystem.

files

data

)

Stores a user context provided as argument in the userData attribute of the function.

files

upload(

pathname

content

)

Uploads a file to the filesystem, to the specified full path name.

files