API Reference

Initialize the interface

//Enable this hardware interface
var server = require('@libraries/hardwareInterfaces');
var settings = server.loadHardwareInterface(__dirname);

exports.enabled = settings('enabled');
exports.configurable = true; // can be turned on/off/adjusted from the web frontend

if (exports.enabled) {

// place your interface code here

}

loadHardwareInterface(_dirName)

  • _dirName (String) Must use string _dirName and returns the path to executed file
  • Returns (Object) Returns content of the settings json file stored for this interface

Returns access to the stored settings for this Interface

var settings = server.loadHardwareInterface(__dirname);

addNode(object, tool, node, type, position)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • type (String) Name of the node Type. The server needs to have a node of this type; otherwise, it will use a default type.
  • position (Object) [Optional] {x: float, y: float} object for the node’s starting position. otherwise random.

Adds a new node to a Tool. If the Tool does not exist, it automatically generates a default tool with the tool-name. If the Object does not exist, it automatically creates a default object with the object-name. This function should be the first you call to initialize all required nodes.

server.addNode("feederStation", "scale", "scaleValue", "node", {x: 1, y: 1})

renameNode(object, tool, oldNode, newNode)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • oldNode (String) Name of existing Node
  • newNode (String) new name for the existing Node

Rename an existing node

server.renameNode("feederStation", "scale", "scaleValue", "measurement");

moveNode(object, tool, node, x, y, scale, matrix, loyalty)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • x (String) new x coordinate relative to the node matrix transform
  • y (String) new y coordinate relative to the node matrix transform
  • scale (String) new scale relative to the node matrix transform
  • matrix (Number[16]) new matrix transform
  • loyalty (String) define the loyalty of Object (grounPlane, Object, world, …)

Move a node to a new possition.

server.moveNode("feederStation", "scale", "measurement", 1, 1, 1, identityMatrix, "object");

removeNode(object, tool, node)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node

Remove node from a Tool.

server.removeNode("feederStation", "scale", "measurement");

attachNodeToGroundPlane(object, tool, node, shouldAttachToGroundPlane)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • shouldAttachToGroundPlane (Boolean) Define if Node is attached to the grounPlane

Lets you attach your Node to the ground plane. This is similar to loyalty, and eventually, an API around loyalty will replace this functionality.

server.attachNodeToGroundPlane("feederStation", "scale", "measurement", true)

clearObject(object, tool)

  • object (String) Name of Object
  • tool (String) Name of Tool

In case your Object handles a lot of changes to the nodes, use this function to clear the memory of unused nodes. You must call this function after you have initialized all your nodes. Otherwise, you lose data.

server.clearObject("feederStation", "scale");

removeAllNodes(objectName, tool)

  • object (String) Name of Object
  • tool (String) Name of Tool

Remove all nodes from your Tool.

server.removeAllNodes("feederStation", "scale");

reloadNodeUI(objectName)

  • object (String) Name of Object

Force every Spatial Toolbox that has access to your spatial Tool to refresh its data about your Spatial Tool.

server.reloadNodeUI("feederStation");

write(object, tool, node, value, mode, unit, unitMin, unitMax)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • value (Number) The new value for the Node. The range must be between 0.0 and 1.0.
  • mode (String) [optional] Data mode. Currently, f for float is the only supported choice.
  • unit (String) [optional] The unit of your data such as ‘kg’, ‘minutes’, ‘liter’,…
  • unitMin (String) [optional] value range minimum
  • unitMax (String) [optional] data range maximum

Write flow data to a node owned by the Spatial Tool within your Object. This flow data is of a simple floating data type with values between 0.0 and 1.0. The example below, writes 0.5 to the node = “nodeName”, unit = kg, min = 0, max = 10 and the last entry tells that the value is only updated on change. The resulting Value will be 5 kg.

server.write("feederStation", "scale", "measurement", 0.5, "f", "kg", 0, 10);

addReadListener(object, tool, node, callBack)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • callback (Function)
  • Returns flowDataObject (Object) flow data object for the Node

Add a read listener to read value changes from a node.

server.addReadListener("feederStation", "scale", "measurement", function(flowDataObject){
    var value = flowDataObject.value;
    var unit = flowDataObject.unit;
});

removeReadListeners(object, tool)

  • object (String) Name of Object
  • tool (String) Name of Tool

It removes all ReadListeners currently running for a tool.

server.addReadListener("feederStation", "scale");

map(x, in_min, in_max, out_min, out_max)

  • x (Number) Input Value
  • in_min (Number) Input Minimum
  • in_max (Number) Input Maximum
  • out_min (Number) Output Minimum
  • out_max (Number) Output Maximum
  • Returns (Object) Result

It scales an input value to the scope of an output value. Use this function to scale the data flow scale of 0.0 - 1.0 to the scale of your units.

var scaleValue = 0.5
var outputValue = server.addReadListener(scaleValue, 0.0, 1.0, 0.0, 10.0);

writePublicData(object, tool, node, dataObject, data)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • dataObject (String) Key to select a dataObject within public Data
  • data (Object/String/Number) Data you want to store with the key

PublicData is a JSON object that contains data objects specified by the node definition. You need to finetune your Tool via specific node types. publicData allows you to handle complex data among the server-side node program and the Spatial Tool. The Value can contain any JSON encoded data.

spatialInterface.writePublicData("feederStation", "scale", "measurement", "lastMeasurements", [0, 1, 0.1, 0, 2]);

addPublicDataListener(object, tool, node, dataObject, callBack)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • dataObject (String) This is a key to select an object within publicData.
  • callback (Function)
  • Returns value (Object/String/Number) returns the stored data.

Add a read listener for publicData to read value changes for a defined Key. These changes are synchronized with the Edge Server and any Spatial Toolbox interacting with the Tool.

spatialInterface.addReadPublicDataListener("feederStation", "scale", "measurement", "lastMeasurements", function(value){
    var publicDataValue = value;
});

addConnectionListener(object, tool, node, callBack)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • node (String) Name of Node
  • callback (Function)
  • Returns link (Object) returns a link object

Listen for when there is a new link associated with the Node.

server.addConnectionListener("feederStation", "scale", "measurement", function(link){
    var newLink = link;
});

getAllObjects()

  • Returns (Object) returns all objects.

Returns a pointer to all known objects

server.getAllObjects();

getKnownObjects()

  • Returns (Object) returns all known objects in the format {uuid : {version:"", protocol:"", ip:""}, ...}

Get all known objects among the entire known network.

var knownObjects = server.getKnownObjects();

getAllFrames(object) // should be renamed to getAllTools

  • object (String) Name of Object
  • Returns (Object) returns an object with all tools for a single object

Return all tools attached to an object.

var allTools = server.getAllFrames("feederStation");

getAllNodes(object, tool)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • Returns (Object) returns an object with all nodes for a single tool

Return all nodes attached to a tool.

var allNodesForTool = server.getAllNodes("feederStation", "scale");

getAllLinksToNodes(object, tool)

  • object (String) Name of Object
  • tool (String) Name of Tool
  • Returns (Object) returns an object with all links stored with a single tool

Return all nodes attached to a tool.

var allLinksStoredWithTool = server.getAllLinksToNodes("feederStation", "scale");

subscribeToNewFramesAdded(objectName, callback) // should be tools

  • object (String) Name of Object
  • callback (Function)
  • Returns tool (Object) returns reference to the Tool added

It will trigger a callback anytime a new tool gets added to Object.

server.subscribeToNewFramesAdded("feederStation", function(tool){
    var newtool = tool;
});

subscribeToReset(objectName, callback)

  • object (String) Name of Object
  • callback (Function)

The callback is triggered when the system is reset, or Git is resetting the system.

server.subscribeToReset("feederStation", function(){
    // called when system is reset
});

subscribeToUDPMessages(callback)

  • callback (String)
  • Returns (Object) UDP messages

Subscribe to UDP messages. You can use this for listening to action messages that are used to keep the overall system updated.

server.subscribeToNewFramesAdded("feederStation", function(udpMsg){
    var aMessage = udpMsg;
});

pushUpdatesToDevices(object)

  • object (String) Name of Object

Force all Spatial Toolbox Applications to reload this Object.

server.pushUpdatesToDevices("feederStation");

activate(object)

  • object (String) Name of Object

Activate an Object. It will be visible to the Spatial Toolbox. By default, all new Objects are active.

server.activate("feederStation");

deactivate(object)

  • object (String) Name of Object

Deactivate an Object. It will be visible to the Spatial Toolbox. By default, all new Objects are active.

server.deactivate("feederStation");

getObjectIdFromObjectName(object)

  • object (String) Name of Object
  • Returns (Object) Object UUID

Get UUID of Object via Name

var ObjectUuid = server.getObjectIdFromObjectName("feederStation");

addEventListener(option, callBack)

  • option (String) Options for System. Use any of these strings reset, shutdown, initialize
  • callback (Function)

Callback for all kinds of system events. Currently supported: reset, shutdown, initialize.

server.addEventListener("reset", function(){
    // place code here for when the system executes a reset
});