com.yoctopuce.YoctoAPI

Class YMagnetometer

java.lang.Object

com.yoctopuce.YoctoAPI.YFunction

com.yoctopuce.YoctoAPI.YSensor

com.yoctopuce.YoctoAPI.YMagnetometer

public class YMagnetometer
extends YSensor

YMagnetometer Class: magnetometer control interface, available for instance in the Yocto-3D-V2 The YSensor class is the parent class for all Yoctopuce sensor types. It can be used to read the current value and unit of any sensor, read the min/max value, configure autonomous recording frequency and access recorded data. It also provides a function to register a callback invoked each time the observed value changes, or at a predefined interval. Using this class rather than a specific subclass makes it possible to create generic applications that work with any Yoctopuce sensor, even those that do not yet exist. Note: The YAnButton class is the only analog input which does not inherit from YSensor.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	YMagnetometer.TimedReportCallback TimedReportCallback for Magnetometer
static interface	YMagnetometer.UpdateCallback Deprecated UpdateCallback for Magnetometer

Field Summary

Fields

Modifier and Type	Field and Description
protected int	_bandwidth
protected YMagnetometer.TimedReportCallback	_timedReportCallbackMagnetometer
protected YMagnetometer.UpdateCallback	_valueCallbackMagnetometer
protected double	_xValue
protected double	_yValue
protected double	_zValue
static int	BANDWIDTH_INVALID invalid bandwidth value
static double	XVALUE_INVALID invalid xValue value
static double	YVALUE_INVALID invalid yValue value
static double	ZVALUE_INVALID invalid zValue 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	YMagnetometer(String func)
protected	YMagnetometer(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 YMagnetometer	FindMagnetometer(String func) Retrieves a magnetometer for a given identifier.
static YMagnetometer	FindMagnetometerInContext(YAPIContext yctx, String func) Retrieves a magnetometer for a given identifier in a YAPI context.
static YMagnetometer	FirstMagnetometer() Starts the enumeration of magnetometers currently accessible.
static YMagnetometer	FirstMagnetometerInContext(YAPIContext yctx) Starts the enumeration of magnetometers currently accessible.
int	get_bandwidth() Returns the measure update frequency, measured in Hz.
double	get_xValue() Returns the X component of the magnetic field, as a floating point number.
double	get_yValue() Returns the Y component of the magnetic field, as a floating point number.
double	get_zValue() Returns the Z component of the magnetic field, as a floating point number.
int	getBandwidth() Returns the measure update frequency, measured in Hz.
double	getXValue() Returns the X component of the magnetic field, as a floating point number.
double	getYValue() Returns the Y component of the magnetic field, as a floating point number.
double	getZValue() Returns the Z component of the magnetic field, as a floating point number.
YMagnetometer	nextMagnetometer() Continues the enumeration of magnetometers started using yFirstMagnetometer().
int	registerTimedReportCallback(YMagnetometer.TimedReportCallback callback) Registers the callback function that is invoked on every periodic timed notification.
int	registerValueCallback(YMagnetometer.UpdateCallback callback) Registers the callback function that is invoked on every change of advertised value.
int	set_bandwidth(int newval) Changes the measure update frequency, measured in Hz.
int	setBandwidth(int newval) Changes the measure update frequency, measured in Hz.

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

BANDWIDTH_INVALID

public static final int BANDWIDTH_INVALID

invalid bandwidth value

See Also:

Constant Field Values

XVALUE_INVALID

public static final double XVALUE_INVALID

invalid xValue value

See Also:

Constant Field Values

YVALUE_INVALID

public static final double YVALUE_INVALID

invalid yValue value

See Also:

Constant Field Values

ZVALUE_INVALID

public static final double ZVALUE_INVALID

invalid zValue value

See Also:

Constant Field Values

_bandwidth

protected int _bandwidth

_xValue

protected double _xValue

_yValue

protected double _yValue

_zValue

protected double _zValue

_valueCallbackMagnetometer

protected YMagnetometer.UpdateCallback _valueCallbackMagnetometer

_timedReportCallbackMagnetometer

protected YMagnetometer.TimedReportCallback _timedReportCallbackMagnetometer

Constructor Detail

YMagnetometer

protected YMagnetometer(YAPIContext ctx,
                        String func)

Parameters:

func - : functionid

YMagnetometer

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

get_bandwidth

public int get_bandwidth()
                  throws YAPI_Exception

Returns the measure update frequency, measured in Hz.

Returns:

an integer corresponding to the measure update frequency, measured in Hz

Throws:

YAPI_Exception - on error

getBandwidth

public int getBandwidth()
                 throws YAPI_Exception

Returns the measure update frequency, measured in Hz.

Returns:

an integer corresponding to the measure update frequency, measured in Hz

Throws:

YAPI_Exception - on error

set_bandwidth

public int set_bandwidth(int newval)
                  throws YAPI_Exception

Changes the measure update frequency, measured in Hz. When the frequency is lower, the device performs averaging. Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters:

newval - : an integer corresponding to the measure update frequency, measured in Hz

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

setBandwidth

public int setBandwidth(int newval)
                 throws YAPI_Exception

Changes the measure update frequency, measured in Hz. When the frequency is lower, the device performs averaging. Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters:

newval - : an integer corresponding to the measure update frequency, measured in Hz

Returns:

YAPI.SUCCESS if the call succeeds.

Throws:

YAPI_Exception - on error

get_xValue

public double get_xValue()
                  throws YAPI_Exception

Returns the X component of the magnetic field, as a floating point number.

Returns:

a floating point number corresponding to the X component of the magnetic field, as a floating point number

Throws:

YAPI_Exception - on error

getXValue

public double getXValue()
                 throws YAPI_Exception

Returns the X component of the magnetic field, as a floating point number.

Returns:

a floating point number corresponding to the X component of the magnetic field, as a floating point number

Throws:

YAPI_Exception - on error

get_yValue

public double get_yValue()
                  throws YAPI_Exception

Returns the Y component of the magnetic field, as a floating point number.

Returns:

a floating point number corresponding to the Y component of the magnetic field, as a floating point number

Throws:

YAPI_Exception - on error

getYValue

public double getYValue()
                 throws YAPI_Exception

Returns the Y component of the magnetic field, as a floating point number.

Returns:

a floating point number corresponding to the Y component of the magnetic field, as a floating point number

Throws:

YAPI_Exception - on error

get_zValue

public double get_zValue()
                  throws YAPI_Exception

Returns the Z component of the magnetic field, as a floating point number.

Returns:

a floating point number corresponding to the Z component of the magnetic field, as a floating point number

Throws:

YAPI_Exception - on error

getZValue

public double getZValue()
                 throws YAPI_Exception

Returns the Z component of the magnetic field, as a floating point number.

Returns:

a floating point number corresponding to the Z component of the magnetic field, as a floating point number

Throws:

YAPI_Exception - on error

FindMagnetometer

public static YMagnetometer FindMagnetometer(String func)

Retrieves a magnetometer 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 magnetometer is online at the time it is invoked. The returned object is nevertheless valid. Use the method YMagnetometer.isOnline() to test if the magnetometer is indeed online at a given time. In case of ambiguity when looking for a magnetometer 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 magnetometer, for instance Y3DMK002.magnetometer.

Returns:

a YMagnetometer object allowing you to drive the magnetometer.

FindMagnetometerInContext

public static YMagnetometer FindMagnetometerInContext(YAPIContext yctx,
                                                      String func)

Retrieves a magnetometer 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 magnetometer is online at the time it is invoked. The returned object is nevertheless valid. Use the method YMagnetometer.isOnline() to test if the magnetometer is indeed online at a given time. In case of ambiguity when looking for a magnetometer 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 magnetometer, for instance Y3DMK002.magnetometer.

Returns:

a YMagnetometer object allowing you to drive the magnetometer.

registerValueCallback

public int registerValueCallback(YMagnetometer.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(YMagnetometer.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

nextMagnetometer

public YMagnetometer nextMagnetometer()

Continues the enumeration of magnetometers started using yFirstMagnetometer(). Caution: You can't make any assumption about the returned magnetometers order. If you want to find a specific a magnetometer, use Magnetometer.findMagnetometer() and a hardwareID or a logical name.

Returns:

a pointer to a YMagnetometer object, corresponding to a magnetometer currently online, or a null pointer if there are no more magnetometers to enumerate.

FirstMagnetometer

public static YMagnetometer FirstMagnetometer()

Starts the enumeration of magnetometers currently accessible. Use the method YMagnetometer.nextMagnetometer() to iterate on next magnetometers.

Returns:

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

FirstMagnetometerInContext

public static YMagnetometer FirstMagnetometerInContext(YAPIContext yctx)

Starts the enumeration of magnetometers currently accessible. Use the method YMagnetometer.nextMagnetometer() to iterate on next magnetometers.

Parameters:

yctx - : a YAPI context.

Returns:

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