Class: WirelessTag

WirelessTag(tagManager, tagData)

new WirelessTag(tagManager, tagData)

The cloud instance of a Wireless Tag. One WirelessTagManager can manage multiple Wireless Tags. A user will not normally need to create instances directly; instead they are found, and created by WirelessTagManager#discoverTags.

Parameters:
Name Type Description
tagManager WirelessTagManager

the tag manager instance that discovered this tag
tagData Object

the object comprising the tag's status properties, as returned by the API endpoint.
Properties:
Name Type Description
uuid string

unique identifier for the tag (r/o)
slaveId number

number enumerating all tags associated with a tag manager, thus only unique for a tag manager (r/0)
name string

the (user-assigned) name of the tag (r/w)
tagType number

a numeric code identifying the type of the tag (r/o)
alive boolean

whether the tag is "alive" (r/o)
rev number

a numeric code identifying the hardware revision of a tag (r/o)
updateInterval number

the interval in seconds at which the tag should update the cloud with the latest data (r/w) (when setting the value, the change must be put into effect by WirelessTag#setUpdateInterval)
lowPowerMode boolean

whether or not the tag is in low power receiving mode (low power mode can considerably prolong battery life, at the expense of needing longer to respond to the tag manager) (when setting the value, the change must be put into effect by WirelessTag#setLowPowerMode)
Source:

Members

callAPI :function

see WirelessTagPlatform.callAPI

Type:
  • function
Source:

data :object

the JSON object returned by the cloud API

Type:
  • object
Source:

wirelessTagManager :WirelessTagManager

Type:
Source:

Methods

bounceUpdateLoop()

Stops and then starts again the automatic update loop for this tag, if one was currently active. Otherwise does nothing.

Source:

canBeep()

Whether the tag can beep.

Source:

canExternalTempProbe()

Whether an external probe for measuring temperature can be connected to the tag.

Source:

canHighPrecTemp()

Whether the tag's temperature sensor is high-precision (> 8-bit).

Source:

canMotionTimeout()

Whether the tag's motion sensor can time out.

Source:

canPlayback()

Whether the tag can play back data recorded while offline.

Source:

createSensor() → {WirelessTagSensor}

Creates (and subsequently caches) a sensor object for the given type of sensor. A sensor object created in this way will subsequently be available as property tag.zzzzSensor, where zzzz is the type of the sensor.

Note that no further initialization involving the cloud API is performed, and so this method behaves mostly as a factory. Specifically this means that the returned sensor object will not have its sensor configuration data loaded.

Source:
Returns:
Type
WirelessTagSensor

discoverSensors() → {Promise}

Discovers the [sensor objects]{@ink WirelessTagSensor} supported by this tag. More specifically, for each sensor capability of the tag, initializes the sensor object.

Emits a discover event for each newly created sensor object once it completes initialization. For previously created sensor objects no discover event will be emitted.

Source:
Returns:

Resolves to a list of initialized WirelessTagSensor objects, representing the sensors supported by this tag.

Type
Promise

eachSensor(action) → {Array}

Invokes the given action on each previously created sensor object, and returns the results as an array. The default action if none is specified simply returns the sensor object, and hence results in the list of (previously created) sensor objects.

Note that this method will not create or initialize sensor objects that would be supported by the tag but have not been initialized or created yet.

Parameters:
Name Type Description
action function

the function to invoke for each sensor object
Source:
Returns:

the results of each invocation

Type
Array

hardwareFacts() → {Array.<string>}

Obtains list of positive capabilities (canXXX()) and facts (isYYY(), hasZZZ()). Does not include sensor capabilities, see WirelessTag#sensorCapabilities for that.

Source:
Returns:
Type
Array.<string>

hasAccelerometer()

Whether the tag's motion sensor is an accelerometer.

Source:

hasBatterySensor()

Whether the tag reports battery charge status. (All non-virtual tags do.)

Source:

hasCurrentSensor()

Whether the tag has a current sensor.

Note that the current sensor tag has been discontinued, so this will now always return false.

Source:

hasEventSensor()

Whether the tag has an 'event' sensor. This is a virtual rather than a physical sensor. Events include 'Moved', 'Opened', etc, and are reported by tags with motion, light, Reed, and PIR sensors.

Source:

hasHumiditySensor()

Whether the tag has a humidity sensor.

Source:

hasLightSensor()

Whether the tag has a light sensor.

Source:

hasMoistureSensor()

Whether the tag has a moisture sensor.

Source:

hasMotionSensor()

Whether the tag has a motion sensor.

Source:

hasOutOfRangeSensor()

Whether the tag tracks and reports out of range status. (All non-virtual tags do.)

Source:

hasPIRSensor()

Whether the tag has a PIR (motion) sensor.

Source:

hasReedSensor()

Whether the tag has a Reed sensor.

Source:

hasSecondaryTempSensor()

Whether the tag has an secondary temperature sensor available concurrent with a primary one.

For tags that can measure temperature in different ways but for which one temperature sensor stands in for the other (which currently includes the GE Protimeter model of the Outdoor tags), this will return false.

Source:

hasSignalSensor()

Whether the tag reports the signal strength from the tag manager. (All non-virtual tags do.)

Source:

hasTempSensor()

Whether the tag has a temperature sensor.

Source:

hasWaterSensor()

Whether the tag has a water sensor.

Source:

initializeSensor(sensorType) → {Promise}

Obtains the sensor object of the given type for this tag. If the sensor object hasn't been created yet for this tag, creates and initializes it.

Note that before completion of initialization, the sensor's configuration will not be loaded, and hence actions depending on it will not work correctly. This includes, for example, reading the temperature in the configured unit (°C/°F), because the unit is part of the sensor configuration.

Emits a discover event for a newly created sensor object once it completes initialization.

Parameters:
Name Type Description
sensorType string

the type of the sensor for which to initialize the sensor object
Source:
Returns:

Resolves to the sensor object. If it was newly created, resolves once initialization of the sensor object completes.

Type
Promise

isCamera()

Whether the tab object represents a Dropcam camera.

Source:

isExternalTempProbe()

Whether the tag is (i.e., requires) an external temperature probe.

In contrast to canExternalTempProbe, if true there is no alternative for measuring temperature.

Source:

isHTU()

Whether the tag's temperature sensor is high-precision (> 8-bit).

Deprecated:
Source:

isKumostat()

Whether the tag object represents a linked thermostat.

Source:

isNest()

Whether the tag object represents a Nest thermostat.

Source:

isOutdoorTag()

Whether the tag is of the Outdoor series.

Tag models of the Outdoor series use external probes for temperature and/or humidity, and feature a water and dustproof enclosure.

Source:

isPhysicalTag()

Whether the tag object represents a physical rather than a virtual tag.

Source:

isWeMo()

Whether the tag object represents WeMo lights.

Source:

isWeMoLED()

Whether the tag object represents a WeMo LED.

Source:

lastUpdated() → {Date}

When the tag last updated the cloud with its latest data.

Source:
Returns:
Type
Date

liveUpdate(callbackopt) → {Promise}

Similar to WirelessTag#update, but requests that the physical tag posts its current "live" data to the cloud, which will then be fetched.

Therefore, to succeed this method requires a response from the tag to a request issued by the tag manager to which it is associated. If the tag is in lowPowerMode, response can take 5-15 seconds (or even longer).

Emits a data event on success. Note that this does not have to mean that any of the sensor-specific data changed (such as temperature or humidity); all that may have changed could be the lastUpdated() value.

Parameters:
Name Type Attributes Description
callback module:wirelesstags~apiCallback <optional>
Source:
Returns:

Resolves to this tag object once the update completes.

Type
Promise

retryUpdateUntil(success, optionsopt) → {Promise}

Retries calling update() until it is considered successful.

A typical use-case for this method is when as a result of invoking a cloud API method actuating the tag or one of its sensors the tag's updated data do not reflect the change even though the API call returned success. For exampe, an API call to arm a sensor might have succeeded, yet the updated data continue to show the sensor as disarmed. Most of the time this discrepancy will resolve itself after some time by simply continuing to fetch updates from the cloud until the armed status is properly reflected.

This method will wait an exponentially increasing amount of time between consecutive retries, and by default will give up after a certain number of unsuccessful attempts (see parameter options and their defaults).

Note that if update() rejects with anything other than a OperationIncompleteError it will not be retried.

Parameters:
Name Type Attributes Description
success function

A function evaluating whether the update is to be considered successful or not. It is passed the tag object and a number giving the attempt, and is expected to return a value evaluating to true if retries should stop. Otherwise, the function should throw a RetryUnsuccessfulError.
options object <optional>

options for controlling the retries, see DEFAULT_RETRY_OPTIONS for defaults.

Properties
Name Type Attributes Description
minTimeout number <optional>

the minimum amount of time in milliseconds to wait between retries
maxTimeout number <optional>

the maximum amount of time in milliseconds to wait between retries
retries number <optional>

the number of times to retry before giving up
Source:
Returns:

Resolves to the tag if retrying is eventually considered successful, and rejects with an OperationIncompleteError otherwise.

Type
Promise

sensorCapabilities() → {Array.<string>}

Obtains the list of sensor types supported by this tag, such as light, humidity, temp (for temperature), etc.

Source:
Returns:
Type
Array.<string>

setLowPowerMode(valueopt, callbackopt) → {Promise}

Turns the low power mode of the tag on or off. Does nothing if the requested mode is already the one that is active.

Note that tags of older hardware revisions don't necessarily support a low power mode. Their low power mode will seem off, but an attempt to turn it on will result in an error.

Parameters:
Name Type Attributes Description
value boolean <optional>

whether to enable (true) or disable (false) low power mode; if omitted, the value of the lowPowerMode property will be used
callback module:wirelesstags~apiCallback <optional>
Source:
Returns:

Resolves to this tag object when the operation completes successfully. Will retry updating until the tag's data reflect the requested value. Rejects with an OperationIncompleteError if this is still not the case after the default number of retries.

Type
Promise

setUpdateInterval(valueopt, callbackopt) → {Promise}

Sets the interval at which the physical tag corresponding to this tag object should update the cloud with its current data. Does nothing if the value to be set is already equal to the currently active update interval.

Parameters:
Name Type Attributes Description
value number <optional>

the new update interval in seconds; if omitted, the update interval will be set to the value of the updateInterval property
callback module:wirelesstags~apiCallback <optional>
Source:
Returns:

Resolves to this tag object when the operation completes successfully. Will retry updating until the tag's data reflect the new update interval. Rejects with an OperationIncompleteError if this is still not the case after the default number of retries.

Type
Promise

startUpdateLoop(minWaitopt) → {number}

Start auto-updating (see update()) this tag object from the cloud according to the update interval configured for the tag (see property updateInterval and setUpdateIJnterval()).

Parameters:
Name Type Attributes Description
minWait number <optional>

the minimum amount of time in milliseconds to wait before invoking the next update call to the cloud API (defaults to MIN_UPDATE_LOOP_WAIT)
Source:
Returns:

The ID of the timer triggering the next update call.

Type
number

stopUpdateLoop()

Stops the automatic update loop for this tag if one was running. Does nothing otherwise.

This will be called automatically if the platform object through which this tag object was obtained (directly or indirectly) is disconnected.

Source:

toString() → {string}

String representation of the tag and its data. Includes a reference to the tag manager (as name and mac), properties, time data were last posted to cloud, the tag's hardware facts and sensor capabilities, and its version.

Source:
Returns:
Type
string

update(callbackopt) → {Promise}

Updates the tag object's data from the cloud. How current the data are will depend on the interval at which the actual tag posts its latest data to the cloud (property updateInterval).

Emits a data event if the update results in new data being fetched. Note that "new data" does not have to mean that any of the sensor-specific data changed (such as temperature or humidity).

Parameters:
Name Type Attributes Description
callback module:wirelesstags~apiCallback <optional>
Source:
Returns:

Resolves to this tag object once the update completes.

Type
Promise

updateUntil()

Similar to WirelessTag#retryUpdateUntil, except that the first attempt to update is made immediately, and success() is called first without the retry attempt number.

Hence, if the initial call to success() evaluates to true, no retry will be made. Otherwise, retries are passed to retryUpdateUntil().

Source:

version()

The version of the tag as a string.

Source: