Class: WirelessTagPlatform

WirelessTagPlatform(optionsopt)

new WirelessTagPlatform(optionsopt)

Instantiates WirelessTagPlatform.

Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Description
log String <optional>

a custom log function.
errorHandler function <optional>

a function returning a custom error handler, will be passed a callback function.
apiBaseURI String <optional>

the base URI of the API server if hosted on a different server than the default (API_BASE_URI)
factory Object <optional>

a factory for tag and tag manager objects, see WirelessTagPlatform.factory which will be used by default
Source:

Members

(static) APICallError

Generic error calling cloud API.

Source:

(static) DuplicateEthCmdError

Error calling cloud API because the same command was sent again before a response to the first.

Source:

(static) InvalidOperationError

Error calling cloud API because the requested operation is not valid

Source:

(static) OperationIncompleteError

The cloud API call failed to complete. Typically this means the API call itself succeeded, but the object's attributes failed to update to reflect the state change.

Source:

(static) OperationUnsupportedError

Thrown if the attempted cloud API call is not supported for the object for which it was made.

Source:

(static) RetryUnsuccessfulError

Thrown if trying to complete or retry a previously incomplete or failed operation fails.

Source:

(static) TagDidNotRespondError

Error calling cloud API because tag needed to but did not respond.

Source:

(static) TagManagerOfflineError

Error calling cloud API because the tag manager is offline.

Source:

(static) TagManagerTimedOutError

Error calling cloud API because the tag manager needed to respond but timed out

Source:

(static) UnauthorizedAccessError

Error calling cloud API because logged in user is not authorized.

Source:

apiBaseURI :string

see default (API_BASE_URI)

Type:
  • string
Source:

callAPI :function

see WirelessTagPlatform.callAPI

Type:
  • function
Source:

connect :function

alias for WirelessTagPlatform#signin

Type:
  • function
Source:

connecting :boolean

Whether or not this object is currently in the process of connecting (i.e., signing in).

Type:
  • boolean
Since:
  • 0.6.0
Source:

disconnect :function

alias for WirelessTagPlatform#signoff

Type:
  • function
Since:
  • 0.6.0
Source:

factory :WirelessTagPlatform~factory

Type:
Since:
  • 0.6.0
Source:

isConnected :function

alias for WirelessTagPlatform#isSignedIn

Type:
  • function
Source:

Methods

(static) callAPI(uri, reqBody, callbackopt) → {Promise}

Performs a call to the cloud JSON API. Users should not normally need to call this method directly.

Note that the method tries to infer necessary pre-steps based on the value of 'this'. It is thus meant to be called as an instance method, with this set to the instance in the library's class hierarchy from where the call would be coming. For example, tag-specific calls should have 'this' bound to a WirelessTag instance.

Parameters:
Name Type Attributes Description
uri string

the uri for the API endpoint to be called; will be prefixed with the base URI if not an absolute URI.
reqBody object

the request body as an object
callback module:wirelesstags~apiCallback <optional>

note that this method will only call this in the event of error, and it is the caller's responsibility to call it with the appropriately processed return value in case of success.
Source:
Returns:

Resolves to the value of the 'd' property of the response body from the API endpoint (or the body itself if there is no 'd' property). Invokes error handler function on error. The default handler will rethrow the error, resulting in rejecting the promise.

Type
Promise

(static) create(optionsopt) → {WirelessTagPlatform}

Creates a WirelessTagPlatform instance, using the given options for initializing. In contrast to the constructor, this method will first attempt to load default configuration using WirelessTagPlatform.loadConfig.

Parameters:
Name Type Attributes Description
options Object <optional>

overrides options found in the default configuration loaded using WirelessTagPlatform.loadConfig.

Properties
Name Type Attributes Description
log String <optional>

a custom log function.
errorHandler String <optional>

a function returning a custom error handler, will be passed a callback function.
apiBaseURI String <optional>

the base URI of the API server if hosted on a different server than the default
Source:
Returns:
Type
WirelessTagPlatform

(static) factory(platformopt) → {WirelessTagPlatform~factory}

Creates and returns a factory for Wireless Tag objects, specifically tag and tag manager objects. It is the default factory.

Parameters:
Name Type Attributes Description
platform WirelessTagPlatform <optional>

the platform instance that will be using the factory. Can be omitted, but then any attempt to invoke cloud API-relying methods of the created objects will fail.
Since:
  • 0.6.0
Source:
Returns:
Type
WirelessTagPlatform~factory

(static) loadConfig() → {Object}

Loads config information, which presently consists primarily of connection options.

The algorithm will attempt to read the file CONFIG_NAME (in JSON format) in the executing user's home directory if the file exists. It will then take username and password from the environment (ENV_USERNAME and ENV_PASSWORD), which allows to use the environment to override settings in the configuration file.

Source:
Returns:
Type
Object

discoverTagManagers(queryopt, callbackopt) → {Promise}

Retrieves the tag managers available to the connected account. The list is optionally filtered depending on the supplied query parameter.

Note that using the 'query' parameter as opposed to filtering the returned tag manager objects will really only be useful to prevent 'discover' events from being fired for undesired tag manager objects. The filtering does not happen at the API endpoint, and so has almost no performance benefits, unless there are many tag managers under the account and the 'discover' event listener were somehow expensive to execute.

Parameters:
Name Type Attributes Description
query Object <optional>

an object with keys and values that a tag manager data object returned by the API has to meet. The most useful ones are likely 'name' and 'mac'. Consult the GetTagManagers JSON API for possible keys.
callback module:wirelesstags~apiCallback <optional>

if provided, query must be provided too, even if as value undefined.
Source:
Fires:
Returns:

resolves to an array of (optionally filtered) WirelessTagManager instances

Type
Promise

discoverTags(queryopt, callbackopt) → {Promise}

Retrieves the tags available to the connected account. The list is optionally filtered depending on the supplied query parameter.

This method offers an alternative discovery path compared to discovering tag manager objects first (through WirelessTagPlatform#discoverTagManagers), and then for each one finding its associated tags. In the case of multiple tag managers this method will be more efficient, because the respective Web Service API endpoints do not support filtering results server-side anyway.

Note that tag manager objects newly created as a side effect will generate 'discover' events, and the tag manager objects will in turn fire 'discover' events for each of their associated tags.

Parameters:
Name Type Attributes Description
query Object <optional>

an object with keys and values that a tag data object returned by the API has to meet. The most useful ones are likely name and uuid. Consult the GetTagForSlaveId JSON API for possible keys. The special key wirelessTagManager can be used to add a query object for tag managers (see WirelessTagPlatform#discoverTagManagers).
callback module:wirelesstags~apiCallback <optional>

if provided, query must be provided too, even if as value undefined.
Since:
  • 0.6.0
Source:
Fires:
Returns:

resolves to an array of WirelessTag instances associated with tag managers accessible to the logged-in account.

Type
Promise

eachTagManager(action) → {Array}

Invokes the given action on each tag manager object currently cached, and returns the results as an array. If no action is specified, return the currently cached tag manager objects.

Parameters:
Name Type Description
action function

the function to invoke for each tag manager object
Since:
  • 0.6.2
Source:
Returns:

the results of each invocation

Type
Array

findTagManager(mac, callbackopt) → {Promise}

Retrieves the tag manager with the given MAC identifier. If the matching object is cached from an earlier call to this or the WirelessTagPlatform#discoverTagManagers method, the cached object is returned. Otherwise the matching object, if one is available and accessible to the logged-in account, is retrieved from the cloud.

Note that the discover event is only fired if the tag manager wasn't cached yet.

Parameters:
Name Type Attributes Description
mac string

the MAC identifier for the tag manager
callback module:wirelesstags~apiCallback <optional>
Since:
  • 0.6.0
Source:
Fires:
Returns:

resolves to the matching WirelessTagManager instance if one is accessible to the logged-in account, and to undefined otherwise.

Type
Promise

getTagManager(mac) → {WirelessTagManager}

Retrieves the tag manager object with the given MAC identifier from the cache.

Note that this method will not consult an API endpoint if the object is not yet cached. Hence, no 'discover' event will be fired.

Parameters:
Name Type Description
mac string

the MAC identifier for the tag manager
Since:
  • 0.6.0
Source:
Returns:

the matching WirelessTagManager instance if one is cached, and undefined otherwise.

Type
WirelessTagManager

isSignedIn(callbackopt) → {Promise}

Tests whether this instance is signed in to the cloud API. (This used to be named isConnected() prior to v0.6.0, which remains an alias.)

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

resolves to true if signed in, and false otherwise

Type
Promise

retryOnError(enableopt) → {boolean}

Queries and/or sets whether failed API calls should be retried. By default this is off.

Note that failed calls are only retried under certain conditions, and only for a certain number of times. At present, the condition is that failure be due to the tag not responding, and the call is retried only once, after waiting WAIT_BEFORE_RETRY milliseconds.

Parameters:
Name Type Attributes Description
enable boolean <optional>

on set, whether or not to enable retrying
Source:
Returns:

whether or not retrying is currently enabled

Type
boolean

selectTagManager(tagManager, callbackopt) → {Promise}

Selects the given tag manager for subsequent API calls that expect it, if the tag manager is not already selected. Note that the library will call this automatically, and so a user will not normally need to do so.

Parameters:
Name Type Attributes Description
tagManager WirelessTagManager

the tag manager instance to select
callback module:wirelesstags~apiCallback <optional>
Source:
Returns:

resolves to the tag manager instance

Type
Promise

signin(opts, callbackopt) → {Promise}

Signs in to the cloud API with the given credentials. Because there is no persistent connection, here this is synonymous with connecting. (This used to be named connect() prior to v0.6.0, which remains an alias.)

Parameters:
Name Type Attributes Description
opts Object

connection parameters

Properties
Name Type Description
username String

the username (email) for connecting
password String

the password for connecting
callback module:wirelesstags~apiCallback <optional>
Since:
  • 0.6.0
Source:
Fires:
Returns:

resolves to 'this' upon success

Type
Promise

signoff(callbackopt) → {Promise}

Signs off from the cloud API, which here is synonymous with disconnecting.

Parameters:
Name Type Attributes Description
callback module:wirelesstags~apiCallback <optional>
Since:
  • 0.6.0
Source:
Fires:
  • WirelessTagPlatform#event:disconnect
Returns:

resolves to 'this' upon success

Type
Promise

Type Definitions

factory

Type:
  • Object
Properties:
Name Type Description
createTag function

expects two parameters, the WirelessTagManager instance with which the tag object to be created is associated, and the tag's attributes as an object (typically this is returned by the cloud API)
createTagManager function

expects one parameter, the tag manager's attributes as an object (typically this is returned by the cloud API).
Source:

Events

connect

Connect event. Emitted after the platform object successfully connects to the cloud.

Type:
Source:

discover

Discover event. Emitted for every WirelessTagManager instance discovered.

Type:
Source: