JavaScript API Library

The JavaScript API Library allows web based applications to interact with a gateway's runtime process.

The JavaScript API Library files are placed into the www/devicewise directory within the Staging Browser area of the file system when the gateway is installed or updated. 

The JavaScript API Library files can be hosted in a standalone HTTP Server by copying the deviceWISE library files to the desired location. 

The JavaScript API Library is meant to replace the WebSocket API Extension feature. If you are upgrading from the WebSocket API Extension feature, see Upgrading from the WebSocket API Extension to the JavaScript API Library.

Because the JavaScript API Library support is dependent on the HTTP Server, it is not supported on the following product:

  • Mitsubishi MESInterface-IT

Gateway HTTP Server

To support the JavaScript API calls into the gateway, the gateway's HTTP Server must be Started.

The status of the gateway's HTTP Server can be viewed using the Workbench -> Administration -> HTTP Server tab. For more information, seeHTTP Server.

Setup

To create a web page that makes use of the JavaScript API library, the following links must be included in the head of the main HTML page.

Assuming the location of the JavaScript API libraries remain in a deviceWISE folder location. If the JavaScript API Library is relocated, the script src must point to the new location. 

JavaScript Script Includes 
<script src="devicewise/jquery-3.1.0.min.js"></script>
<script src="devicewise/devicewiseClient.js"></script>
<script src="devicewise/devicewiseConstants.js"></script>
<script src="devicewise/devicewiseDiagnostics.js"></script>
<script src="devicewise/devicewiseVariable.js"></script>
<script src="devicewise/devicewiseSQLite.js"></script>
<script src="devicewise/devicewiseDevice.js"></script>
<script src="devicewise/devicewiseTrigger.js"></script>
<script src="devicewise/devicewiseProject.js"></script>
<script src="devicewise/devicewiseChannel.js"></script>
<script src="devicewise/devicewiseSystem.js"></script>

deviceWISE types

Datatype codes are accessed using the following definitions:

Datatype Codes 
devicewise.INT1
devicewise.INT2
devicewise.INT4 
devicewise.INT8
devicewise.UINT1
devicewise.UINT2
devicewise.UINT4
devicewise.UINT8
devicewise.FLOAT4
devicewise.FLOAT8
devicewise.BOOL
devicewise.STRING

Authentication Functions

devicewise.login(endpoint, username, password, callbackSuccess, callbackError)

Login to a deviceWISE gateway runtime and set the endpoint that the JavaScript APIs will use to perform function calls. 

This login will persist the session until the session times out or a user logout occurs.

Before you login, you will need to create a new user in the gateway, using the Workbench. Use the Workbench -> Administration -> Security tab to display the Security panel, then select the Users tab.
Create a new User with the following credentials

  • Name: jsapi
  • Password: 9cZbK9HFUtcTZY3Z
  • Role: select one of the Roles that are defined on the gateway.
    For complete information on Users, Roles, and Policies, see: Security.

After creating the new user, you will be able to login with the following:

  • endpoint - HTTP Server Endpoint to connect to. 
    • Examples would be: 
      • Secure: "https://_ipaddress_of_devicewise_gateways_http_server_ssl_address:_port_of_devicewise_gateways_http_server_ssl_address".
        • https://127.0.0.1:8443
      • Open: ""http://_ipaddress_of_devicewise_gateways_http_server_address:_port_of_devicewise_gateways_http_server_address".
        • http://127.0.0.1:8080
  • username - jsapi
  • password - 9cZbK9HFUtcTZY3Z
  • callbackSuccess() - Callback function called upon successful authentication.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.oauthLogin(endpoint, jwt, callbackSuccess, callbackError)

Login to a deviceWISE gateway runtime using a  JSON Web Token (JWT).

Before this function can be used, the gateway must have the OAuth2 extension added. For more information, see OAuth 2.0 integration.

Once the OAuth2 extension is added to the gateway, you will be able to login with the following:

  • endpoint - HTTP Server Endpoint to connect to. 
    • Examples: 
      • Secure: "https://_ipaddress_of_devicewise_gateways_http_server_ssl_address:_port_of_devicewise_gateways_http_server_ssl_address".
      • Open: "http://_ipaddress_of_devicewise_gateways_http_server_address:_port_of_devicewise_gateways_http_server_address".
  • jwt - The JWT that is returned by your OAuth2 authentication server.
  • callbackSuccess() - Callback function called upon successful authentication.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.logout()

Logout from the deviceWISE gateway runtime.

Variable Functions

devicewise.read(device, variable, type, count, length, callbackSuccess, callbackError)

Read a variable.

  • device - Device to be read from.
  • variable - Variable to be read. Full path must be supplied (ex. folder1.folder2.variableName). If reading from arrays include the index you want to begin reading from (ex. arrayVariable[0]).
  • type - deviceWISE data type.
  • count - Number of elements to read from an array. Use a -1 for scalar reads.
  • length - Length of the deviceWISE data type. Used for STRING data types. Use a -1 to inherit length for other types.
  • callbackSuccess(data) - Callback function that returns data read.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.write(device, variable, type, count, length, data, callbackSuccess, callbackError)

Write to a variable.

  • device - Device to write to.
  • variable - Variable to be written. Full path must be supplied (ex. folder1.folder2.variableName). If writing to arrays include the index you want to begin writing from (ex. arrayVariable[0]).
  • type - deviceWISE data type.
  • count - Number of elements to write to an array. Use a -1 for scalar writes.
  • length - Length of the deviceWISE data type. Used for STRING data types. Use a -1 to inherit length for other types.
  • data - data to be written to the variable.
  • callbackSuccess() - Callback function called upon successful completion.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.
  • Response - In the response, status is the error code of the variable read. 0 is success, non-zero is a deviceWISE error code. You can use workbench to look up the error.

devicewise.subscribe(device, variable, rate, type, count, length, callbackSuccess, callbackError, callbackPublishReceived)

Subscribe to a variable. Subscribing to multiple elements of an array will result in a subscription created for each element.

  • device - Device containing the variable to subscribe to.
  • variable - Variable to be subscribed to. Full path must be supplied (ex. folder1.folder2.variableName). If subscribing to arrays include the index you want to begin subscribing from (ex. arrayVariable[0]).
  • rate - Poll rate, in seconds, for the subscription.
  • type - deviceWISE data type.
  • count - Number of elements to subscribe to for an array. Use a -1 for scalar writes.
  • length - Length of the deviceWISE data type. Used for STRING data types. Use a -1 to inherit length for other types.
  • callbackSuccess(subscriptionID) - Callback function called upon successful completion. Returns the subscription's ID.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.
  • callbackPublishReceived(dataArray) - Callback called when data publish is received for the given subscription. Returns an array with the variable's data.

devicewise.unsubscribe(subscriptionID, callbackSuccess, callbackError)

Unsubscribe from a variable.

  • subscriptionID - ID of the subscription to unsubscribe from.
  • callbackSuccess() - Callback called upon successful removal of the subscription.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.unsubscribeAll(callbackSuccess, callbackError)

Unsubscribe from all current variable subscriptions.

  • callbackSuccess(removedCount) - Callback called upon successful removal of the subscription.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Device Functions

devicewise.deviceList(callbackSuccess, callbackError)

Get a list of the defined devices on the deviceWISE gateway.

  • callbackSuccess(deviceArray) - Callback called upon reception of device list. Contains an array of devices. Each device is represented with a name, a type, state, and details about the device's current metadata.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Response

  • Name - Name of Device
  • Type - The device type from the deviceWISE driver code listing. The driver code listing is in the section, deviceWISE Driver Code Listings.
  • State:
    • 1 - The device is Started.
    • 2 - The device is Stopped.
    • 3 - The device is Disabled.
    • 4 - The device is Starting
    • 5 - The device is Stopping
    • 6 - Unknown
  • Last State Change - Last time the state change occurred.
  • Last Modified - Last time the device was modified. 
  • Options - Options set on the device for internal processing.
  • Status (Optional) - Indicates the health of the device.
  • Ex-Status (Optional) - Indicates the health of the device.

Example device list response:

device.list 
[
    {
        "name": "device1",
        "type": 1,
        "state": 2,
        "lastStateChange": 0,
        "lastModified": 1516644055833,
        "options": 3192
    },
    {
        "name": "device2",
        "type": 9,
        "state": 1,
        "lastStateChange": 1521669085502,
        "lastModified": 1520978825926,
        "options": 2104,
        "status": 0,
        "exstatus": 0
    }
]

devicewise.deviceInfo(device, list_options, callbackSuccess, callbackError)

Get device information.

  • device - Name of the device to query for information.
  • list_options - Controls the types of items to be returned by the API as following:
    • 1 - Device properties;
    • 2 - Device variables;
    • 4 - Device structures;
    • 8 - Device runtime status;
    • 16 - Device errors;
    • 32 - Device attributes;
    • 64 - Device commands;
    • 256 - Device variables in a different format;
    • 512 - Device structure in a different format.
  • callbackSuccess(deviceObject) - Callback containing a device object with device information.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Response

  • Name - The name of the device.
  • Type - The device type from the deviceWISE driver code listing. The driver code listing is in the section, deviceWISE Driver Code Listings.
  • Type Name - The device model name from the deviceWISE driver code listing.
  • State:
    • 1 - The device is Started.
    • 2 - The device is Stopped.
    • 3 - The device is Disabled.
    • 4 - The device is Starting
    • 5 - The device is Stopping
    • 6 - Unknown
  • Options - Options set on the device for internal processing.
  • Desc - Description of the device.
  • Device Properites (Optional) - An array of device properties. 
    • Name - Device property name.
    • Value - Device property value.
  • Attributes (Optional) - An array of the device attributes.
    • Name - Device attribute name.
    • Name NLS - Device attribute display name.
    • Value - Device attribute value. This can be either a string or integer value.
  • Variable Info (Optional) - An array of the device variables.
    • Name - Variable name
    • Type - Variable data type
    • Structure Id (Optional) - For variables that are structures, the structural id value of the structure the variable represents. 
    • X Dimension(Optional) - The size of the array for one dimensional arrays or the size of the first dimension for two or three dimensional array variables.
    • Y Dimension (Optional) - The size of the second dimension for two or three dimensional array variables.
    • Z Dimension (Optional) - The size of the third dimension for three dimensional array variables. 
    • Length (Optional) - The size of the variable or an element within an array of variables.
    • Count (Optional) - Total number of elements within the variable if the variable is an array.
    • Offset (Optional) - Element offset within an array of items.
    • Bitno(Optional) - Bit offset within an array of items.
    • X Start (Optional) - The x dimension offset of the item within a two or three dimension array.
    • Y Start (Optional) - The y dimension offset of the item within a two or three dimension array.
    • Z Start (Optional) - The z dimension offset of the item within a two or three dimension array.
    • Casts (Optional) - Additional data type masks that can be applied to the variable when reading it's data
    • Desc (Optional) - The description of the variable
    • Options - Numeric codes that define the read and write properties of the variable.
  • Structures (Optional) - An array of structures associated with the device.
    • Name - Structure Name
    • Structure Id - Numeric number that identifies a structure within the device that it has been added to.
    • Length - The size of the structure.
    • Options - Numeric codes that define the read and write properties of the structure as well as its displayable properties.
    • Variable Info - An array of the variables within the structure. 
      • See above Variable Info for parameters.
  • Commands (Optional) - An array of device commands.
    • Name -  Command Name.
    • Name NLS (Optional) - Command display name.
    • Desc NLS (Optional)  - Command display description.
    • Options - Options set on the command for internal processing.
  • Mapped Descriptions (Optional) - An array of mapped descriptions associated with the device.
    • Name - Name of the description.
    • Desc - Details of the description.
  • Runtime Status (Optional) - An array of runtime status details. 
    • Status - Indicates the health of the runtime status.
    • Ex Status - Indicates the health of the runtime status.
    • Error Repeated - Count of repeated errors.
    • Last Error Time - Last time an error occured.
    • Start Time - How long the device has been started. 
    • Stop Time -  How long the device has been stopped.
    • Average Read Time - Average time it takes to read from the device.
    • Last Read Time - Last time the device was read from.
    • Total Reads - Total amount of reads that have happened on the device.
    • Average Write Time - Average time it takes to write to the device.
    • Last Write Time - Last time the device was written to.
    • Total Writes - Total amount of writes that have happened on the device.
    • Average Work Queue Wait Time - Average amount of time a queued item has waited on the device. 
    • Work Queue Depth - Current amount of queued items.
    • Runtime Status - Indicates the current health of the runtime status.
  • Device Errors (Optional) - An array of device errors.
    • First Time - First time an error occured.
    • Last Time - Last time an error occured.
    • Variable (Optional) - Variable name, if the error occured on a variable.
    • Status - Indicates the health of the device.
    • Ex Status - Indicates the health of the device.
    • Repeat Count - How many times an error has occured.

Example device information response:

device.info 
 {
    "name": "device",
    "type": 9,
    "typeName": "Global Variables",
    "state": 1,
    "options": 2104,
    "description": "",
    "attributes": [
        {
            "name": "Structure Count",
            "nameNls": "0",
            "value": "0"
        },
        {
            "name": "Structure Member Count",
            "nameNls": "0",
            "value": "0"
        },
        {
            "name": "Total Variable Count",
            "nameNls": "148",
            "value": "148"
        },
        {
            "name": "Variable Count",
            "nameNls": "25",
            "value": "25"
        }
    ],
    "runtimeStatus": [
        0,
        0,
        0,
        0,
        13,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
    ]
}

devicewise.deviceDataTypeEnum(callbackSuccess, callbackError)

Get the list of defined device types.

  • callbackSuccess(ArrayOfDeviceTypes) - Callback containing an array of datatype objects.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Response 

  • Name - The name of the device.
  • Name NLS ID - The ID for the name of the device.
  • Type - The device type from the deviceWISE driver code listing. The driver code listing is in the section, deviceWISE Driver Code Listings.
  • Type Name - The device model name from the deviceWISE driver code listing.
  • Options - Options set on the device for internal processing.
    • Options is a flag that can contain any of the following bit mask:
      • 1 - Readable - The deviceWISE item can be read from;
      • 2 - Writable - The deviceWISE item can be writen to;
      • 4 - Subscribable - The deviceWISE item can be subscribed to;
      • 8 - Deletable - The deviceWISE item can be deleted;
      • 16 - Editable - The deviceWISE item can be edited to;
      • 32 - Controllable - The deviceWISE item can be started or stopped manually;
      • 64 - Hotedit - The item can be edited without stopping;
      • 128 - Internal;
      • 256 - Display value as hex - Display the value of the deviceWISE item in hexadecimal format;
      • 512 - Display index as hex - The array offsets for the deviceWISE item is in hexadecimal format;
      • 1024 - Refreshable - Variable list can be refreshed;
      • Creatable - New device can be created;
      • 4096 - Internal;
      • 8192 - Sort variables - The deviceWISE items are to be sorted;
      • 16384 - Show status code in hex - Display the extended status code for the deviceWISE item in hexadecimal format;
      • 32768 - Driver only support even length - Accept input of Strings with an even number of characters;
      • 65536 - Driver is a local IO device;
      • 132072 - Internal;
      • 262144 - Internal;
      • 524288 - Display index as octal - The array offsets for the deviceWISE item is in octal format.
  • Licensed - Boolean value of whether or not the device type is licensed.
  • Family Name (Optional) - Name of the family.
  • Family NLS ID (Optional) - NLS ID belonging to the family name.
  • Display Order (Optional) - Order of display.
  • Category Name (Optional) - Category Name.
  • Category NLS ID (Optional) - NLS ID belonging to the category name.
  • Type Names (Optional) - An array of the deviceWISE Data types associated with the device type.
    • Type - Data type ID.
    • Name - Name of the type.
  • Property Descriptions (Optional) - An array of the properties associated with the device type.
    • Key - Property Description Key.
    • Name - Property Description Name. 
    • Name NLS - ID associated with the Property Description Name.
    • Desc NLS - ID associated with the Property Description Description.
    • Required (Optional) - Present and set to true if the property description is set to required.
    • Advanced (Optional) - Present and set to true if the property description is set to advanced.
    • Re-Validate (Optional) - Present and set to true if the property description is set to re-validate.
    • Read Only (Optional) - Present and set to true if the property description is set to read only.
    • Sort (Optional) - Present and set to true if the property description is set to sort.
    • Hex (Optional) -  Present and set to true if the property description is set to hex.
    • Type Object (Optional) - 
      • String Object - If the Property Description is a String
        • Type - Set to "string".
        • Default (Optional) - The string default value.
      • Integer Object - If the Property Description is an Integer
        • Type - Set to "integer".
        • Default - The integer default value.
        • Min - Minimum value.
        • Max - Maximum value. 
      • Option Object - If the Property Description is an Option
        • Type - Set to "option".
        • Default (Optional) - The indexed value of the option.
      • Check Object - If the Property Description is a Check
        • Type - Set to "check"
        • Default: Boolean default value of the check. 
      • Other Object - If the Property Description is Other
        • Type - Set to the value of the type.
        • Default - Set to the value of the default for the type. 
    • Conditionals (Optional) - An array of condition objects within the property. 
      • Key - The conditions key.
      • Value - The conditions value.
      • Condition - Whether it is "equal" or "notequal"

Example data type enumeration response: 

devicetype.enum 
[
    {
        "typeId": 6,
        "name": "Node Connection",
        "nameNlsId": 31104,
        "options": 3128,
        "familyName": "PeerLINK",
        "familyNlsId": 31102,
        "displayOrder": 0,
        "propertyDescriptions": [
            {
                "key": "peer_address",
                "name": "IP Address",
                "nameNls": 31011,
                "descNls": 31021,
                "required": true,
                "type": "string"
            },
            {
                "key": "peer_user",
                "name": "Username",
                "nameNls": 31112,
                "descNls": 31122,
                "required": true,
                "type": "string"
            },
            {
                "key": "peer_password_encoded",
                "name": "Password",
                "nameNls": 31113,
                "descNls": 31123,
                "required": true,
                "type": "encrypted_password",
                "default": ""
            },
            {
                "key": "peer_type",
                "name": "Connection Type",
                "nameNls": 31116,
                "descNls": 31126,
                "advanced": true,
                "type": "string",
                "default": "deviceWISE"
            },
            {
                "key": "timeout",
                "name": "Timeout",
                "nameNls": 31115,
                "descNls": 31125,
                "advanced": true,
                "type": "integer",
                "default": 10000,
                "min": 5000,
                "max": 60000
            }
        ],
        "licensed": true
    },
    {
        "typeId": 8,
        "name": "Aliases",
        "nameNlsId": 31133,
        "options": 3192,
        "familyName": "System",
        "familyNlsId": 31131,
        "displayOrder": 0,
        "propertyDescriptions": [
            {
                "key": "mode",
                "name": "Aliasing Mode",
                "nameNls": 31136,
                "descNls": 31137,
                "required": true,
                "type": "option",
                "default": 0,
                "options": "Variable,Device"
            },
            {
                "key": "Variables",
                "name": "Variables",
                "nameNls": 31138,
                "descNls": 31139,
                "required": true,
                "type": "variables_aliases",
                "default": "",
                "conditions": [
                    {
                        "key": "mode",
                        "value": "Variable",
                        "condition": "equal"
                    }
                ]
            },
            {
                "key": "device_name",
                "name": "Device Name",
                "nameNls": 31134,
                "descNls": 31135,
                "required": true,
                "sort": true,
                "type": "device_list",
                "default": "",
                "conditions": [
                    {
                        "key": "mode",
                        "value": "Device",
                        "condition": "equal"
                    }
                ]
            }
        ],
        "licensed": true
    }
]


devicewise.deviceStart(device, callbackSuccess, callbackError)

Start a device.

  • device - Device to start.
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.deviceStop(device, callbackSuccess, callbackError)

Stop a device.

  • device - Name of the device to stop.
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Trigger Functions

devicewise.triggerList(projectName, callbackSuccess, callbackError)

Get a list of triggers for a given project.

  • projectName - Name of the project to get a list of triggers from.
  • callbackSuccess(triggerArray) - Callback returning an array of triggers. Each trigger contains a name, a state, and details about the triggers current metadata.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Response

  • Name - The name of the trigger
  • State:
    • 1 - The trigger is Started.
    • 2 - The trigger is Stopped.
    • 3 - The trigger is Disabled.
    • 4 - The device is Starting
    • 5 - The device is Stopping
    • 6 - Unknown
  • Last State Change - Last time the state change occurred.
  • Last Modified - Last time the trigger was modified. 
  • Context (Optional) - Details about the type of trigger. 
  • Last Fired - Time last fired. 
  • Count Success - Count of successful fires.
  • Count Pending - Count of pending fires.
  • Count Failure - Count of failed fires.
  • Count Overflow - Count of overflowed executions.
  • Average Execution - Average amount of time the trigger takes to execute. 
  • Last User (Optional) - Last user to execute the trigger.
  • Load State - 
    • 1 - The trigger is Loaded.
    • 2 - The trigger is Unloaded.
    • 3 - The trigger is Loading.
    • 4 - The trigger is Unloading.
  • Execution Max - Max execution time.
  • Execution Min - Minimum execution time.
  • Execution Last - Last time executed.
  • Count In Queue - Current Queue count.
  • Queue Watermark - Queue watermark count.
  • Queue Watermark Timestamp - Queue watermark timestamp.
  • Overview String (Optional) - Overview string of the trigger event.

Example trigger list response:

trigger.list 
[
    {
        "name": "trigger1",
        "state": 1,
        "lastStateChange": 1521553567599,
        "lastMofified": 1521659012961,
        "context": "On-Demand|1,0~|user",
        "lastFired": 0,
        "countSuccess": 0,
        "countPending": 0,
        "countFailure": 0,
        "countOverflow": 0,
        "averageExecution": 0,
        "loadState": 2,
        "executionMax": 0,
        "executionMin": 0,
        "executionLast": 0,
        "countInQueue": 0,
        "queueWatermark": 0,
        "queueWatermarkTimestamp": 0
    },
    {
        "name": "trigger2",
        "state": 1,
        "lastStateChange": 1521588762359,
        "lastMofified": 1521659012994,
        "context": "SubTrigger|1,0~|user",
        "lastFired": 0,
        "countSuccess": 0,
        "countPending": 0,
        "countFailure": 0,
        "countOverflow": 0,
        "averageExecution": 0,
        "loadState": 2,
        "executionMax": 0,
        "executionMin": 0,
        "executionLast": 0,
        "countInQueue": 0,
        "queueWatermark": 0,
        "queueWatermarkTimestamp": 0
    }
]

devicewise.triggerStart(projectName, triggerName, callbackSuccess, callbackError)

Start a trigger.

  • projectName - Name of the project containing the trigger.
  • triggerName - Name of the trigger.
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.triggerFire(projectName, triggerName, callbackSuccess, callbackError)

Fire a trigger.

  • projectName - Name of the project containing the trigger.
  • triggerName - Name of the trigger.
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.triggerStop(projectName, triggerName, callbackSuccess, callbackError)

Stop a trigger.

  • projectName - Name of the project containing the trigger.
  • triggerName - Name of the trigger.
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.subtriggerFire(projectName, triggerName, reportingEnabled, variables, callbackSuccess, callbackError)

Fires a subtrigger.

  • projectName - Name of the project containing the subtrigger.
  • triggerName - Name of the subtrigger.
  • reportingEnabled - Boolean value indicating if the subtrigger should enable reporting when fired.
  • variables - An array of the input variables keyed off the variable name, with the value of the data. 
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Project Functions

devicewise.projectList(callbackSuccess, callbackError)

Get a list of defined projects on the deviceWISE gateway.

  • callbackSuccess(projectArray) - Callback returning an array of projects. Each project contains a name, a state, and details about the projects current metadata.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Response

  • Name - The name of the project
  • State:
    • 1 - The project is Started.
    • 2 - The project is Stopped.
  • Last State Change - Last time the state change occured.
  • Last Modified - Last time the project was modified. 
  • Desc (Optional) - Description of the project.

Example project list response:

project.list 
[
    {
        "name": "project1",
        "state": "2",
        "laststatechange": "1521659013021",
        "lastmodified": "1521060865720"
    },
    {
        "name": "project2",
        "state": "1",
        "laststatechange": "1521659026142",
        "lastmodified": "1521659023559"
    }
]


devicewise.projectStart(projectName, callbackSuccess, callbackError)

Start a project.

  • projectName - Name of the project.
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.projectStop(projectName, callbackSuccess, callbackError)

Stop a project.

  • projectName - Name of the project.
  • callbackSuccess() - Callback called upon success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Channel Functions

devicewise.channelSubscribe(channel, callbackSuccess, callbackError, callbackPost)

Subscribe to a deviceWISE channel.

  • channel - channel to subscribe to.

    DW Available Channels 
    PROJECT
TRIGGER
ALERT
DISKWATCH_CHANNEL
EXPORT
FTPSERVER
LICENSE
LOGGING
TIME
SESSION
SYSTEM
SECURITY
DEVICE
MAPPER
VARGROUP
USEROP
ASSET
SAF
MAPLOG
TR50 SAF QUEUE
TR50 SAF CONNECTIONS
TR50 SAF PROFILE
  • callbackSuccess() - Callback called on success.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.
  • callbackPost(ChannelObject) - Callback called when a channel post is received. The response is an array of objects containing post specific information.

Response - Example:

channel.subscribe Data 
{ "id": 32, "channel": "TRIGGER", "code": 4, "data": [ "New Danlaw", "Danlaw Event JSON", "3", "admin" ] }
{ "id": 32, "channel": "TRIGGER", "code": 4, "data": [ "test", "Start Dev", "1" ] }
{ "id": 31, "channel": "DEVICE", "code": 1, "data": [ "TestDevice" ] }
  • Data is dependent on channel type. 

devicewise.channelUnsubscribe(id, callbackSuccess, callbackError)

Unsubscribe from a deviceWISE channel.

  • subscriptionID - ID of the subscription to unsubscribe from.
  • callbackSuccess() - Callback called upon successful removal of the subscription.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

devicewise.channelUnsubscribeAll(callbackSuccess, callbackError)

Unsubscribe from all current channel subscriptions.

  • callbackSuccess(removedCount) - Callback called upon successful removal of the subscription.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Diagnostic Functions

devicewise.networkPing(IPAddress, numPings, callbackSuccess, callbackError)

Ping an IP address.

  • IPAddress - IP address to ping.
  • numPings - Number of pings to send.
  • callbackSuccess(pingArray) - Callback called on success. Returns array with response times for pings in milliseconds.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Response:

Array of response times in milliseconds

[ping1response, ping2response, ping3response, ping4response]

Example network ping response:
[2, 3, 2, 2]

System Functions

devicewise.referenceList(sourceType, source, options, callbackSuccess, callbackError)

Get a reference list.

  • sourceType - The type of the object to get references for.

    Available Reference Types 
    Administration
Local Database
Security
TR50 Connection
device
alerts
attention bit
dbtable
ftp server
os
license
policy
project
report
role
system
timesync
transaction
transport
trigger
user
  • source - The name of the object to get references for. Must be the same type as sourceType.
  • Reference Direction:
    • 0 - Forward - Referenced by source
    • 1 - Backwards - References of source
    • 2 - Both - All references of the source and by the source.
  • callbackSuccess(referenceObject) - Callback called on success. Returns a reference object containing reference information.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Returned Reference Response:

  • Name - Name of the source.
  • Type - The type of the source
  • References - An array of objects referencing the source.
    • Flag - The reference direction by ID.
    • Flag Description: Description of the reference direction.
    • Name - Name of the reference.
    • Type - Type of the reference.

Example reference list response:

reference.list 
{
    "name": "TestDevice",
    "type": "device",
    "References": [
        {
            "flag": 1,
            "flagDescription": "Referenced By",
            "name": "test/start_device",
            "type": "trigger"
        },
        {
            "flag": 1,
            "flagDescription": "Referenced By",
            "name": "test",
            "type": "project"
        }
    ]
}

This example is showing that TestDevice is a device that is being referenced by the trigger test/start_device as well as the project test. This makes sense because TestDevice is used by one trigger, test/start_device, which is part of the project test.

SQLite Functions

devicewise.SQLiteExec(query, callbackSuccess, callbackError)

Execute SQLite query.

  • query - Query string to be executed.
  • callbackSuccess(ataObject) - Callback handling SQLite response. Response is an object of data whose structure is based on the query type.
  • callbackError(errorCode, errorMessage) - Callback called if an error occurs. Returns errorCode and errorMessage.

Example SQLiteExec response 1

  • Query: insert into SampleTable values ("samplevalue");

    SQLite Example 
    {
    "affectedRows": 1
}

Example SQLiteExec response 2

  • Query: SELECT * FROM SampleTable;

    SQLite Example 
     {
    "count": 2,
    "table": "SampleTable;",
    "columns": [
        "name"
    ],
    "results": [
        {
            "name": "example_1"
        },
        {
            "name": "example_2"
        }
    ]
}

Error Codes

Error codes can be looked up from the deviceWISE Workbench by selecting the Help menu in the upper right hand corner, and then selecting Error Lookup.

Demo web application

The API_DemoV3.zip is a web browser based application that allows you to test all the JavaScript API Library functions.

The API_DemoV3_Device_TestDevice.dwx includes the sample deviceWISE device for testing the demo web app.

The API_DemoV3_Project_TestProject.dwx includes the sample deviceWISE project and trigger for testing the demo web app.

The  API_DemoV3_SQLite_table_TestTable.dwx includes the sample deviceWISE table for testing the SQLite library function in the demo web app.

To run the demo web application:

  • Update or install the deviceWISE gateway to release 18.2.1 or higher.
  • Make sure the HTTP Server is Started.
  • Import the demo project, trigger, table and device contained in the export files mentioned above.
  • Extract the API_DemoV3.zip files and put them into the gateway's Staging Browser /www directory.
  • Point your browser to http://127.0.0.1:8080/API_Demo/index.html.

The demo web application user interface should look similar to this: