com.yoctopuce.YoctoAPI

Class YVirtualSensor

java.lang.Object

com.yoctopuce.YoctoAPI.YFunction

com.yoctopuce.YoctoAPI.YSensor

com.yoctopuce.YoctoAPI.YVirtualSensor

public class YVirtualSensor
extends YSensor

YVirtualSensor Class: virtual sensor control interface The YVirtualSensor class allows you to use Yoctopuce virtual sensors. These sensors make it possible to show external data collected by the user as a Yoctopuce Sensor. This class inherits from YSensor class the core functions to read measurements, to register callback functions, and to access the autonomous datalogger. It adds the ability to change the sensor value as needed, or to mark current value as invalid.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	YVirtualSensor.TimedReportCallback TimedReportCallback for VirtualSensor
static interface	YVirtualSensor.UpdateCallback Deprecated UpdateCallback for VirtualSensor

Field Summary

Fields

Modifier and Type	Field and Description
protected double	_invalidValue
protected YVirtualSensor.TimedReportCallback	_timedReportCallbackVirtualSensor
protected YVirtualSensor.UpdateCallback	_valueCallbackVirtualSensor
static double	INVALIDVALUE_INVALID invalid invalidValue value

Fields inherited from class com.yoctopuce.YoctoAPI.YSensor

_advMode, _cal, _calibrationParam, _currentRawValue, _currentValue, _highestValue, _iresol, _logFrequency, _lowestValue, _prevTR, _reportFrequency, _resolution, _sensorState, _timedReportCallbackSensor, _unit, _valueCallbackSensor, ADVMODE_IMMEDIATE, ADVMODE_INVALID, ADVMODE_PERIOD_AVG, ADVMODE_PERIOD_MAX, ADVMODE_PERIOD_MIN, CALIBRATIONPARAM_INVALID, CURRENTRAWVALUE_INVALID, CURRENTVALUE_INVALID, HIGHESTVALUE_INVALID, LOGFREQUENCY_INVALID, LOWESTVALUE_INVALID, REPORTFREQUENCY_INVALID, RESOLUTION_INVALID, SENSORSTATE_INVALID, UNIT_INVALID

Fields inherited from class com.yoctopuce.YoctoAPI.YFunction

_advertisedValue, _cacheExpiration, _className, _dataStreams, _func, _funId, _hwId, _lastErrorMsg, _lastErrorType, _logicalName, _serial, _userData, _valueCallbackFunction, _yapi, ADVERTISEDVALUE_INVALID, FUNCTIONDESCRIPTOR_INVALID, LOGICALNAME_INVALID

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	YVirtualSensor(String func)
protected	YVirtualSensor(YAPIContext ctx, String func)

Method Summary

Modifier and Type	Method and Description
int	_invokeTimedReportCallback(YMeasure value)
int	_invokeValueCallback(String value)
protected void	_parseAttr(com.yoctopuce.YoctoAPI.YJSONObject json_val)
static YVirtualSensor	FindVirtualSensor(String func) Retrieves a virtual sensor for a given identifier.
static YVirtualSensor	FindVirtualSensorInContext(YAPIContext yctx, String func) Retrieves a virtual sensor for a given identifier in a YAPI context.
static YVirtualSensor	FirstVirtualSensor() Starts the enumeration of virtual sensors currently accessible.
static YVirtualSensor	FirstVirtualSensorInContext(YAPIContext yctx) Starts the enumeration of virtual sensors currently accessible.
double	get_invalidValue() Returns the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set).
double	getInvalidValue() Returns the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set).
YVirtualSensor	nextVirtualSensor() Continues the enumeration of virtual sensors started using yFirstVirtualSensor().
int	registerTimedReportCallback(YVirtualSensor.TimedReportCallback callback) Registers the callback function that is invoked on every periodic timed notification.
int	registerValueCallback(YVirtualSensor.UpdateCallback callback) Registers the callback function that is invoked on every change of advertised value.
int	set_currentRawValue(double newval) Changes the current value of the sensor (raw value, before calibration).
int	set_invalidValue(double newval) Changes the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set).
int	set_sensorAsInvalid() Changes the current sensor state to invalid (as if no value would have been ever set).
int	set_sensorState(int newval)
int	set_unit(String newval) Changes the measuring unit for the measured value.
int	setCurrentRawValue(double newval) Changes the current value of the sensor (raw value, before calibration).
int	setInvalidValue(double newval) Changes the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set).
int	setUnit(String newval) Changes the measuring unit for the measured value.

Methods inherited from class com.yoctopuce.YoctoAPI.YSensor

_applyCalibration, _decodeAvg, _decodeTimedReport, _decodeVal, _encodeCalibrationPoints, _parseCalibStr, _parserHelper, calibrateFromPoints, FindSensor, FindSensorInContext, FirstSensor, FirstSensorInContext, get_advMode, get_calibrationParam, get_currentRawValue, get_currentValue, get_dataLogger, get_highestValue, get_logFrequency, get_lowestValue, get_recordedData, get_reportFrequency, get_resolution, get_sensorState, get_unit, getAdvMode, getCurrentRawValue, getCurrentValue, getHighestValue, getLogFrequency, getLowestValue, getReportFrequency, getResolution, getSensorState, getUnit, isSensorReady, loadCalibrationPoints, nextSensor, registerTimedReportCallback, registerValueCallback, set_advMode, set_calibrationParam, set_highestValue, set_logFrequency, set_lowestValue, set_reportFrequency, set_resolution, setAdvMode, setHighestValue, setLogFrequency, setLowestValue, setReportFrequency, setResolution, startDataLogger, stopDataLogger

Methods inherited from class com.yoctopuce.YoctoAPI.YFunction

_AddToCache, _clearDataStreamCache, _decode_json_int, _decode_json_string, _download, _escapeAttr, _FindFromCache, _FindFromCacheInContext, _get_json_path_struct, _get_json_path, _is_valid_pass, _json_get_array, _json_get_key, _json_get_string, _parse, _setAttr, _throw, _UpdateTimedReportCallbackList, _UpdateValueCallbackList, _upload, _upload, _uploadEx, clearCache, describe, errMessage, errorMessage, errorType, errType, FindFunction, FindFunctionInContext, FirstFunction, FirstFunctionInContext, functionDescriptor, get_advertisedValue, get_errorMessage, get_errorType, get_friendlyName, get_functionDescriptor, get_functionId, get_hardwareId, get_logicalName, get_module, get_serialNumber, get_userData, getAdvertisedValue, getErrorMessage, getErrorType, getFriendlyName, getFunctionDescriptor, getFunctionId, getHardwareId, getLogicalName, getModule, getUserData, isOnline, isReadOnly, load, loadAttribute, module, muteValueCallbacks, nextFunction, registerValueCallback, set_advertisedValue, set_logicalName, set_userData, setLogicalName, setUserData, toString, unmuteValueCallbacks, userData

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INVALIDVALUE_INVALID

public static final double INVALIDVALUE_INVALID

invalid invalidValue value

See Also:

Constant Field Values

_invalidValue

protected double _invalidValue

_valueCallbackVirtualSensor

protected YVirtualSensor.UpdateCallback _valueCallbackVirtualSensor

_timedReportCallbackVirtualSensor

protected YVirtualSensor.TimedReportCallback _timedReportCallbackVirtualSensor

Constructor Detail

YVirtualSensor

protected YVirtualSensor(YAPIContext ctx,
                         String func)

Parameters:

func - : functionid

YVirtualSensor

protected YVirtualSensor(String func)

Parameters:

func - : functionid

Method Detail

_parseAttr

protected void _parseAttr(com.yoctopuce.YoctoAPI.YJSONObject json_val)
                   throws Exception

Overrides:

_parseAttr in class YSensor

Throws:

Exception

set_unit

public int set_unit(String newval)
             throws YAPI_Exception

Changes the measuring unit for the measured value. Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters:

newval - : a string corresponding to the measuring unit for the measured value

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

setUnit

public int setUnit(String newval)
            throws YAPI_Exception

Changes the measuring unit for the measured value. Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters:

newval - : a string corresponding to the measuring unit for the measured value

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

set_currentRawValue

public int set_currentRawValue(double newval)
                        throws YAPI_Exception

Changes the current value of the sensor (raw value, before calibration).

Parameters:

newval - : a floating point number corresponding to the current value of the sensor (raw value, before calibration)

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

setCurrentRawValue

public int setCurrentRawValue(double newval)
                       throws YAPI_Exception

Changes the current value of the sensor (raw value, before calibration).

Parameters:

newval - : a floating point number corresponding to the current value of the sensor (raw value, before calibration)

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

set_sensorState

public int set_sensorState(int newval)
                    throws YAPI_Exception

Throws:

YAPI_Exception

set_invalidValue

public int set_invalidValue(double newval)
                     throws YAPI_Exception

Changes the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set). Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters:

newval - : a floating point number corresponding to the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set)

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

setInvalidValue

public int setInvalidValue(double newval)
                    throws YAPI_Exception

Changes the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set). Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters:

newval - : a floating point number corresponding to the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set)

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

get_invalidValue

public double get_invalidValue()
                        throws YAPI_Exception

Returns the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set).

Returns:

a floating point number corresponding to the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set)

Throws:

YAPI_Exception - on error

getInvalidValue

public double getInvalidValue()
                       throws YAPI_Exception

Returns the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set).

Returns:

a floating point number corresponding to the invalid value of the sensor, returned if the sensor is read when in invalid state (for instance before having been set)

Throws:

YAPI_Exception - on error

FindVirtualSensor

public static YVirtualSensor FindVirtualSensor(String func)

Retrieves a virtual sensor for a given identifier. The identifier can be specified using several formats:

• FunctionLogicalName
• ModuleSerialNumber.FunctionIdentifier
• ModuleSerialNumber.FunctionLogicalName
• ModuleLogicalName.FunctionIdentifier
• ModuleLogicalName.FunctionLogicalName

This function does not require that the virtual sensor is online at the time it is invoked. The returned object is nevertheless valid. Use the method YVirtualSensor.isOnline() to test if the virtual sensor is indeed online at a given time. In case of ambiguity when looking for a virtual sensor by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name. If a call to this object's is_online() method returns FALSE although you are certain that the matching device is plugged, make sure that you did call registerHub() at application initialization time.

Parameters:

func - : a string that uniquely characterizes the virtual sensor, for instance MyDevice.virtualSensor1.

Returns:

a YVirtualSensor object allowing you to drive the virtual sensor.

FindVirtualSensorInContext

public static YVirtualSensor FindVirtualSensorInContext(YAPIContext yctx,
                                                        String func)

Retrieves a virtual sensor for a given identifier in a YAPI context. The identifier can be specified using several formats:

• FunctionLogicalName
• ModuleSerialNumber.FunctionIdentifier
• ModuleSerialNumber.FunctionLogicalName
• ModuleLogicalName.FunctionIdentifier
• ModuleLogicalName.FunctionLogicalName

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

Parameters:

yctx - : a YAPI context

func - : a string that uniquely characterizes the virtual sensor, for instance MyDevice.virtualSensor1.

Returns:

a YVirtualSensor object allowing you to drive the virtual sensor.

registerValueCallback

public int registerValueCallback(YVirtualSensor.UpdateCallback callback)

Registers the callback function that is invoked on every change of advertised value. 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.

_invokeValueCallback

public int _invokeValueCallback(String value)

Overrides:

_invokeValueCallback in class YSensor

registerTimedReportCallback

public int registerTimedReportCallback(YVirtualSensor.TimedReportCallback callback)

Registers the callback function that is invoked on every periodic timed notification. 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 an YMeasure object describing the new advertised value.

_invokeTimedReportCallback

public int _invokeTimedReportCallback(YMeasure value)

Overrides:

_invokeTimedReportCallback in class YSensor

set_sensorAsInvalid

public int set_sensorAsInvalid()
                        throws YAPI_Exception

Changes the current sensor state to invalid (as if no value would have been ever set).

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

nextVirtualSensor

public YVirtualSensor nextVirtualSensor()

Continues the enumeration of virtual sensors started using yFirstVirtualSensor(). Caution: You can't make any assumption about the returned virtual sensors order. If you want to find a specific a virtual sensor, use VirtualSensor.findVirtualSensor() and a hardwareID or a logical name.

Returns:

a pointer to a YVirtualSensor object, corresponding to a virtual sensor currently online, or a null pointer if there are no more virtual sensors to enumerate.

FirstVirtualSensor

public static YVirtualSensor FirstVirtualSensor()

Starts the enumeration of virtual sensors currently accessible. Use the method YVirtualSensor.nextVirtualSensor() to iterate on next virtual sensors.

Returns:

a pointer to a YVirtualSensor object, corresponding to the first virtual sensor currently online, or a null pointer if there are none.

FirstVirtualSensorInContext

public static YVirtualSensor FirstVirtualSensorInContext(YAPIContext yctx)

Starts the enumeration of virtual sensors currently accessible. Use the method YVirtualSensor.nextVirtualSensor() to iterate on next virtual sensors.

Parameters:

yctx - : a YAPI context.

Returns:

a pointer to a YVirtualSensor object, corresponding to the first virtual sensor currently online, or a null pointer if there are none.