wiser-connector

wiser-connector

Samples data from a Wiser Tracker REST API and reports tag location updates and zone transitions.

Targets ES6+.

Table of Contents

• Install
• Usage
• Connector Options
• Tag Report Properties
• Methods
• Events
• Errors

Install

npm i -S wiser-connector

Usage

Same Process

// import
const { WiserConnector } = require('wiser-connector');

// create connector
const connector = new WiserConnector({
  hostname: '127.0.0.1',
  tagSampleRate: 500, // tag data will be checked every 0.5 seconds
  zoneSampleRate: 30000, // zone data will be checked every 30 seconds
  tagHeartbeat: 1000, // tag updates are reported at most once per second
  port: 3101
});

// start the connector
connector.start();

// listen for events
connector.on(WiserConnector.events.tagHeartbeat, message => {
  console.log(message);
});

// shutdown the connector
connector.shutdown();

---

Connector Options

Name	Type	Default	Description
id	String	WiserConnector	The identifier to use for the connector.
hostname	String	127.0.0.1	The hostname to use to connect to the Wiser REST API.
port	Number	3101	The TCP port to use to connect to the Wiser REST API.
tlsEnabled	Boolean	false	If true, the connector will use https to connect to the Wiser REST API.
tagSampleRate	Number	1000	How often the connector should sample tag data (milliseconds).
zoneSampleRate	Number	30000	How often the connector should sample zone data (milliseconds).
tagHeartbeat	Number	60000	How often tag location changes are reported (milliseconds), independent of zone transitions.

NOTE: Zone transitions are ALWAYS reported no matter what the tagHeartbeat is set to.

---

Tag Report Properties

Property	Type	Description
id	Number	The unique id of the tag report.
error	Number	The estimated error in location calculation.
location	Object	Location coordinates {x: Number, y: Number, z: Number}.
tag	Number	An integer used to identify the tag. Usually printed on the tag in hex format.
timestamp	Number	Unix time in milliseconds.
battery	Number	The current battery voltage of the tag. Anything below 2.8 is considered low.
zones	Object[]	A list of zone IDs {id: number} that the tag is reported to be in.

The location property is an object that contains the x, y, and z coordinates for the tag position.

Example:

{x: 10.2, y: 256.9, z: 34.0}

The zones property is an array of objects that describe which zones the tag is currently in.

Example:

[{ id: 0 }, { id: 1 }, { id: 2 }];

Anchor Properties

Property	Type	Description
id	Integer	Anchor ID
hardwareId	Integer	Hardware ID
firmwareVersion	String	Firmware version
x	Number	X coordinate within the array
y	Number	Y coordinate within the array
z	Number	Z coordinate within the array

Gateway Properties

Property	Type	Description
id	Integer	Gateway ID
ipv4	String	Network IP address
port	Integer	Network TCP port
x	Number	X coordinate within the array
y	Number	Y coordinate within the array
z	Number	Z coordinate within the array

Adapter Properties

Property	Type	Description
id	Integer	Adapter ID
usbAnchor	Integer	USB attached anchor ID
downstreamAdapter	Integer	Downstream adapter ID

Arena Properties

Property	Type	Description
panId	Integer	Unique ID
anchors	[Anchor]	List of anchors
gateways	[Gateway]	List of gateways
adapters	[Adapter]	List of adapters

---

Methods

start

Start the connector with Connector Options or, if not provided, use the options passed to the constructor.

const WiserConnector = require('wiser-connector');
const options = {
  hostname: '192.168.1.9',
  port: 3101,
  tagHeartbeat: 300000
};

const connector = new WiserConnector(options);
connector.start();

// OR

const connector = new WiserConnector();
connector.start(options);

shutdown

Shut down the connector.

connector.shutdown();

status (async)

Returns a Promise that resolves to an Arena object.

connector
  .status()
  .then(arena => {
    console.log(arena);
  })
  .catch(err => {
    console.log(err.message);
  });

// OR

try {
  const arena = await connector.status();
} catch (err) {
  console.log(err.message);
}

Events

Register for events using the values defined in WiserConnector.events or use the event names directly.

tagHeartbeat

Emitted when a tag updates and the time since the last heartbeat is greater than or equal to the configured tagHeartbeat value. See Tag Report Properties.

TIP: Setting tagHeartbeat to 0 will cause every tag update to be reported.

tagEnteredZone & tagExitedZone

Emitted when a tag enters or exits a zone. See event data object definition below.

Property	Type	Description
report	Object	The tag report for the tag that transitioned zones.
zone	Object	Contains the Wiser id and name of the zone where the transition occured.

Example

{
  report: {
    id: 0,
    tag: 31000,
    location: {x: 0, y: 0, z: 0},
    zones: [{id: 0, id: 1}],
    error: 0.0,
    anchors: 5,
    timestamp: 143456789,
    battery: 3.1
  },
  zone: {
    id: 0,
    name: 'Zone A'
  }
}

status

Emitted after a connector's status command is executed in a child process. The data contains the current hardware status information returned from the Wiser REST API /wiser/api/arena endpoint. See Arena Properties

You can also use async/await or then/catch since the status method is asynchronous to get the data without subscribing to the status event.

// .then/.catch
connector
  .status()
  .then(() => {
    // process arena data
  })
  .catch(err => {
    // handle error
  });

// async/await
try {
  const arena = await connector.status();
  // process arena data
} catch (err) {
  // handle error
}

---