Guide for Lab Administrators

Setting up the Web Instrument Service
Introduction

The websfpInstrumentInterface is a software that is automatically started as a service on the NI ELVIS III. It is responsible for the communication between the NI ELVIS III and a web browser.

You can control and configure it via an SSH session, to customize the web instrument behavior. For example, you can change the lease time to keep the device ID for a longer period, or change the signaling server address to use a custom signaling server.

Opening an SSH Session

A Secure Shell (SSH) session enables you to control and configure the NI ELVIS III using the command line interface. The following sections assume you are using SSH. Complete the following steps to open an SSH session.

  1. Make sure the SSH server is enabled on your NI ELVIS III device. You can check it in MAX or the on web configuration page: http://<your device IP>/WIF.html#HOME. You must use IE to open this page.
  2. Install SSH client software to open the session:
    • For Windows OS, SSH client might not be available natively. You must install at least one SSH client software product to continue, such as PuTTY.
    • For Linux OS, SSH client software is available natively.
  3. Open an SSH session by using the command line interface on the host PC:
    ssh admin@<your device IP>
    The default password is empty.

Once the session is opened, you will see admin@<your device name>:~# in the command line interface. All the commands you enter hereafter will be executed by the device.

Controlling the websfpInstrumentInterface Service

The websfpInstrumentInterface service can be started and stopped through an ssh session to the device. From the console, run the following commands to respectively stop, start or restart the service:

/etc/init.d/websfpInstrumentInterface stop
/etc/init.d/websfpInstrumentInterface start
/etc/init.d/websfpInstrumentInterface restart
If you want to run the websfpInstrumentInterface application as a stand alone application, you can use the following command:
/usr/local/natinst/academic/bin/websfpInstrumentInterface

Before starting the application this way, make sure you have stopped the service. Otherwise, the two running instances of the application will interfere with each other.

The default behavior of the application can be modified either through command-line arguments or a custom configuration file. Each of these options are explained in the following sections.

Command-line Arguments

The application has a set of startup arguments that can be used to modify the default behavior. Startup arguments take precedence over any default settings or similar settings read from a configuration file. The list of available startup arguments can be retrieved by passing the help argument.

In the table below, items between angled brackets <> are parameters to be specified.

The following startup arguments can be used:

ArgumentDefault value
help
signaling=<server address>wss://sigserver.multisim.com:1339
config=<path to alternate config file>/etc/natinst/share/websfpInstrumentInterface.json
createDefaultConfig
deviceid=<device ID>
loglevel=<screen output verbosity>info
logtofilefalse
logpath=<path for log file>/var/local/natinst/log/websfpInstrumentInterface.log
help
Display the list of possible arguments for the application and their description

example:

/usr/local/natinst/academic/bin/websfpInstrumentInterface help
example output:
This application has the following optional arguments:

help                    Shows this help text.
                          example: websfpInstrumentInterface help
deviceid=<device id>    Allows you to specify a device id that should be used for the application.
                        WARNING: Using a fixed deviceid reduces security.
                          example: websfpInstrumentInterface deviceid=ELVIS
signaling=<server>      Allows you to specify your own custom signaling server.
                        The signaling server uses the web socket protocol and uses the following format wss://address:port.
                        Note that it is recommended to use a custom configuration file instead for specifying a custom signaling server.
                          example: websfpInstrumentInterface signaling=wss://signaling.university.com:1339
config=<file path>      Specify a custom configuration file to use, normally the program will look for a configuration
                        file in the location /etc/natinst/share/websfpInstrumentInterface.json.
                        If the configuration file is not found, the program will use appropriate defaults.
                          example: websfpInstrumentInterface config=myConfig.json
createDefaultConfig     Create a configuration file using applications default values.
                        This file can than be modified to your needs. By default this file will be written
                        to the default configuration location at /etc/natinst/share/websfpInstrumentInterface.json,
                        but a custom location and name can be specified through the config argument.
                          example: websfpInstrumentInterface createDefaultConfig config=/home/user/config.json
loglevel=<level>        Should be one of: error,warning,info,debug,verbose. Specifies the verbosity of the debug output of the program. By default loglevel=info
                          example: websfpInstrumentInterface loglevel=debug
logtofile               If this parameter is set, the program will log to file instead of the console.
                        If no alternate logpath is specified this will log to /var/local/natinst/websfpInstrumentInterface.log with level info
                          example: websfpInstrumentInterface logtofile
logpath=<path>          Specify a path for the log file.
                        The given directory must exist and be writable
                          example: websfpInstrumentInterface logtofile logpath=websfpInstrumentInterface.log loglevel=debug
                
signaling
Specifies an alternate signaling server. The signaling server is used to establish a connection between the web browser and the NI ELVIS III over the internet or local network. The address must represent the address of a proper web socket based signaling server in the format wss://server_address[:port]. You can also set up a custom signaling server.

example:

/usr/local/natinst/academic/bin/websfpInstrumentInterface signaling=wss://signaling.university.com:1111
config
Specifies the location of a configuration file. By default the application will look for a configuration file in the location: /etc/natinst/share/websfpInstrumentInterface.json. If no configuration file is found, the program will be started using default values. If a custom configuration file is specified on the command line and the specified file cannot be loaded, the application will terminate with an error.

example:

/usr/local/natinst/academic/bin/websfpInstrumentInterface config=/home/admin/customConfig.json
createDefaultConfig
This will create a new configuration file using default values and save it in the default location (/etc/natinst/share/websfpInstrumentInterface.json). Once the file is created, the program will exit. The default configuration file is a good starting point to use when you want to modify any of the default settings for the application. The configuration file uses JSON format and all the items in the file are optional. If an item is missing, the default value for that item will be used. If you want to create the configuration file in different location, use the config attribute.

examples:

/usr/local/natinst/academic/bin/websfpInstrumentInterface createDefaultConfig config=/home/admin/newConfig.json
/usr/local/natinst/academic/bin/websfpInstrumentInterface createDefaultConfig
                
deviceid
This forces a specific device ID to be used for the NI ELVIS III. Normally device IDs are generated by the signaling server and sent to the device. Through this argument you can force a specific device ID to be used. Forcing a specific device ID is not as secure as using the auto-generated device IDs from the signaling server. If someone knows the device ID they can connect to the device. Having a fixed device ID makes it more likely that people will eventually know about it and connect to it. The device ID can include any combination of letters, numbers, hyphens(-) and underscores(_). It is case sensitive.

example:

/usr/local/natinst/academic/bin/websfpInstrumentInterface deviceid=myELVIS
loglevel
This is the verbosity of the console output. The following values can be used, and are in the order of less to more verbose:
  • error: Show errors only
  • warning: Show errors and warnings
  • info: Show errors, warnings and info messages
  • debug: Show all of the above and general debug messages
  • verbose: Show all possible output messages

example:

/usr/local/natinst/academic/bin/websfpInstrumentInterface loglevel=debug
logtofile
This flag tells the application to log to a file instead of the console. The default log location is /var/local/natinst/log/websfpInstrumentInterface.log. The log file location can be changed using the logpath argument. Note that the default service for websfpInstrumentInterface is started with this flag set, so the service by default logs to a file.

example:

/usr/local/natinst/academic/bin/websfpInstrumentInterface logtofile
logpath
If the logtofile argument is specified, the logpath argument can be used to specify an alternate log file location. The path should include the file name of the log file and the specified directory should exists and be writable.

example:

/usr/local/natinst/academic/bin/websfpInstrumentInterface logtofile logpath=/home/admin/mylog.log
Configuration File

A configuration file can be used to control the behavior of the websfpInstrumentInterface application. Using the configuration files is the preferred method of controlling this application. In the case where the application is running as a service, you will need to restart the service after changing settings in the configuration file. This can be done by running:

/etc/init.d/websfpInstrumentInterface restart
However, the preferred way of updating the configuration file is the following :
  1. Stop the service by using:
    /etc/init.d/websfpInstrumentInterface stop
  2. Modify the configuration file.
  3. Test the configuration file by running the application from the command line:
    /usr/local/natinst/academic/bin/websfpInstrumentInterface
  4. Quit the running application by typing "quit" followed by <Enter> or pressing "Ctrl+c".
  5. If everything worked properly with the new configuration, start the service again with:
    /etc/init.d/websfpInstrumentInterface start
In case you end up in a restart loop with the service, you can stop it by using the stop service method mentioned above either from the open SSH session or a new one.

Create a configuration file

A custom configuration file can be created using the createDefaultConfig argument. This is a good start if you want to modify the configuration settings. The configuration file is in JSON format and looks something like this:
{
  "deviceID": {
    "disconnectGracePeriodMinutes": 10,
    "leaseTimeHours": 4
  },
  "deviceid": "",
  "logFileArchiveCount": 4,
  "logFileSizeArchiveThreshold": 1000000,
  "logLevel": "info",
  "logPath": "/var/local/natinst/log/websfpInstrumentInterface.log",
  "signalingServer": "wss://sigserver.measurementslive.com:1339",
  "stunServers": [
    "stun:stun.measurementslive.com:19302",
  ]
}
The exact content might differ depending on the version of the application. Each item in this configuration file can be omitted, in which case the application will use the default value for that item.

Note: Command-line arguments take precedence over similar items in the configuration file.

Config file parameters

The following items can be modified through the configuration file. In the table below, items between angled brackets <> are required and values between square brackets [] are optional.
Element nameDefault value
deviceID
Element nameDefault value
disconnectGracePeriodMinutes10
leaseTimeHours4
deviceid
logFileArchiveCount4
logFileSizeArchiveThreshold1000000
logLevelinfo
logPath/var/local/natinst/log/websfpInstrumentInterface.log
signalingServerwss://sigserver.multisim.com:1339
stunServers[ "stun:stun.multisim.com:3478", "stun:stun.l.google.com:19302", "stun:stun1.l.google.com:19302", "stun:stun2.l.google.com:19302", "stun:stun3.l.google.com:19302", "stun:stun4.l.google.com:19302" ]

Following is a detailed description of the elements mentioned.
deviceID
The "deviceID" object contains settings related to the dynamic device ID generation. A code is generated by the signaling server using a set of default rules. The "deviceID" object contains the rules that can be customized.
leaseTimeHours
The "leaseTimeHours" setting specifies the duration of a "lease" of a device ID. The duration is specified in hours and must be in the range of 1 to 12. The default lease time is 4 hours. After the lease time expires a new device ID will be generated. A lease time of -1 indicates infinite. Note that if the signaling server is restarted for any reason, a new device ID will be generated, even if the lease time is infinite. The device ID is only used to make an initial connection to the NI ELVIS III. Therefore a change to the device ID will NOT have any effect on an already connected device. New connections must use the currently active code and cannot use any previous code.
disconnectGracePeriodMinutes
By default a new device ID is generated every time the lease expires or whenever the device is reconnected to the signaling server (connection happens when the device is turned on). To prevent you from having to use a new device ID every time the connection is lost, a grace period exists before a reconnect event will generate a new device ID. This grace period ONLY applies to reconnects and does not apply to the lease time expiration. The "disconnectGracePeriodMinutes" setting alows you to specify in minutes the grace period and valid values are 0 to 60 minutes. The default is 10 minutes.
deviceid
By default device IDs are automatically assigned by the signaling server. However in some cases it might be desirable to specify a specific device ID to a device that doesn't change. The "deviceid" setting allows you to specify a fixed device ID that should be used by the NI ELVIS III. Please note that specifying a fixed device ID is less secure than having the signaling server generate new device IDs dynamically. Also note that a device ID must be unique, so there is a chance that a device ID will be rejected by the signaling server if you specify one that has already been registered.
logFileArchiveCount
This number specifies how many archive copies of the log file will be kept in the case that log files are saved to disk. The first archive of the logfile will be stored uncompressed while subsequent archives are compressed using gzip. The minimum number of archives that will be kept is 1, while the maximum number that can be specified is 100. The default value is 4. Files will be named with an extension that indicates how old the logfile archive is. Higher numbers indicate older archives. For example in the default case of 4, the log files will be named websfpInstrumentInterface.log (the active log file), websfpInstrumentInterface.log.1 (the previous log file), websfpInstrumentInterface.log.2.gz, websfpInstrumentInterface.log.3.gz and websfpInstrumentInterface.log.4.gz for the older archives. Any archives that would get an higher number than the number specified with the logFileArchiveCount element, will be removed.
logFileSizeArchiveThreshold
This number specifies the threshold size of the log file after which a log file is archived and a new log file is started. While the program is running the log file will grow in size. Once the log file sizes passes the threshold specified with this element, it will be archived and a new log file will be started. The number of archives that is kept around is determined by the logFileArchiveCount element.
logLevel
This is the verbosity level of the logging. Valid values in order of increasing verbosity are: error, warning, info, debug, verbose. The default verbosity is info. It is not recommended to specify verbose in a production environment because of the amount of messages it produces.
logPath
This specifies the location where the log file will be written in the case where to log is written to a file. If the application is started with the logtofile option. This element can be used to speicy the location of the log file. By default log files are written to /var/local/natinst/log/websfpInstrumentInterface.log
signalingServer
The connection between the web browser and the NI ELVIS III is a peer-to-peer connection, but this connection must be set up first. The signaling server is used to allow a web browser and the NI ELVIS III to make the connection by registering themselves. The signaling server matches the web browser with the correct NI ELVIS III. NI provides a default signaling server, but it might be desirable to use a custom signaling server. The "signalingServer" setting in the configuration file allows you to specify an alternate signaling server.
stunServers
For the connection to be made between the NI ELVIS III and a web browser, it may be necessary to go through subnets and firewalls. The stun server is used to determine the best route for this connection to be made. It is possible to have more than one stun server to allow for a higher chance of finding a route between the two peers. The "stunServers" element contains the list of possible stun servers you want to use. See also Setting up STUN Server.
Examples

Command-line argument

To start the websfpInstrumentInterface with a device ID of "test" and connect to the signaling server at sig.university.com with port 1234:
/usr/local/natinst/academic/bin/websfpInstrumentInterface deviceid=test signaling=wss://sig.university.com:1234
To write a default configuration file to the current directory and name the file default.json:
/usr/local/natinst/academic/bin/websfpInstrumentInterface createDefaultConfig config=default.json
To start the application and make it use the configuration at /home/admin/test.json:
/usr/local/natinst/academic/bin/websfpInstrumentInterface config=/home/admin/test.json

Configuration file

The following configuration sets the signaling server to sig.university.com with port 4321:
{
  "signalingServer": "wss://sig.university.com:4321"
}
The following configuration sets the lease time to 2 hours with no grace period:
{
  "deviceID": {
    "disconnectGracePeriodMinutes": 0,
    "leaseTimeHours": 2
  }
}
The following configuration sets the device ID to "test" and provide use Google's stun servers
{
  "deviceid": "test",
  "stunServers": [
    "stun:stun.l.google.com:19302",
    "stun:stun1.l.google.com:19302",
    "stun:stun2.l.google.com:19302",
    "stun:stun3.l.google.com:19302",
    "stun:stun4.l.google.com:19302",
  ]
}
Setting up Custom Signaling Server
Introduction

The signaling server is used to establish a peer-to-peer connection between the NI ELVIS III device and Measurements Live. It also delivers device IDs and gathers device information.

While NI provides a public signaling server running on AWS, you can create your custom signaling server to increase security and control. You can keep your custom signaling server inside a firewall, which is one major way to increase security.

The custom signaling server is a node.js HTTP server application package. You can download, install, customize and run it on your server computer.

Quick Start

Prepare Secure Socket Layer (SSL)

Ensuring a domain name and a corresponding SSL certificate is the very first step to set up a custom signaling server that can be accessed from the internet. Because the online Measurements Live is a webpage using secured HTTP protocol, it cannot open a non-secure web socket session to a signaling server. That means you must setup the signaling server with SSL to enable Measurements Live connection.

There are several ways to get a domain name and a corresponding SSL certificate. You may need help from the IT department of your organization for that.

You must make sure that your internet-facing server works under SSL, otherwise, all types of networking information will be sent in plain text. Anyone on the internet can easily capture plain texts, leads to weak security. A secure server address looks like this: wss://some.domain.name:1339. A non-secure one looks like this: ws://X.X.X.X:1333.

After setting up the signaling server with the following instructions, you should set up a web request transmitter by using the SSL certificate and the domain name. For example, if you set up the server on AWS, you can add a load balancer listener for the server instance, import the SSL certificate files via certificate manager, and bind the certificate to the load balancer listener.

Set up a custom signaling server

Follow these steps to setup your custom signaling server:

  1. Download and install Node.js from http://nodejs.org/en/download. This installer installs the Node Package Manager (npm) at the same time. Make sure the Node.js installation directory is added to the PATH of your system during installation.

    The minimum required version of Node.js is LTS. You need to first install Node.js and npm in order to install and run the signaling server and grab the correct dependencies.

  2. Open a command line interface. Create an installation directory for the signaling server package and navigate to the directory from the command line. For example:

    mkdir signalingserver
    cd signalingserver
  3. Download and install the signaling server node package by using the command line interface:

    npm install --global-style @ni/measurementslive-signalingserver

    You must install the package locally with global style by using the --global-style argument, in order to enable all the features of this package.

  4. Navigate to the package directory:

    cd ./node_modules/@ni/measurementslive-signalingserver/

    All the package commands only work in this directory.

  5. Run the signaling server from the package installation directory by:

    npm start

    A web socket server (non-secure) will be turned on with the URL ws://<server IP>:<port>, and you will see the server log on the command line interface. You can shut down the server by pressing <Ctrl+C>.

    Note: The custom signaling server will only be opened to localhost IP, 127.0.0.1, by default, to prevent potential secure problem while the server has not be completely set. You can change this setting in the configuration file.

  6. Set up a web request transmitter with an SSL certificate and a domain name to upgrade the unsecured URL to a secured URL wss://<domain name>:<port>.

Use the dashboard

The signaling server includes an API that allows you to monitor the server status and the devices and clients connected. An example of how to use this API via the dashboard is included in this package.

Open a new command line interface, navigate to the package directory, and run a built-in HTTP server for the dashboard by:

npm run dashboard

This will start a local HTTP server and print all available HTTP addresses on the console. Enter one address in a web browser and press Enter to go to the dashboard webpage.

In the dashboard, specify your custom signaling server URL in Signaling server address and click Connect. Dashboard Connect

The code for the dashboard is in <package directory>/dashboard. Refer to the code to understand the API and use it to create your own dashboard.

Configure the NI ELVIS III

You must change the configuration of an NI ELVIS III device before connecting it to your custom signaling server.

  1. Open an SSH session to the device from the command line interface by:

    ssh admin@<your device IP>
  2. Create a default config file and change the signaling server address by:

    1. Generate a default configuration file.
      /usr/local/natinst/academic/bin/websfpInstrumentInterface createDefaultConfig
    2. Change signaling server address. Replace <domain name> and <port> with that of your server. The angle brackets should be removed.
      sed -ri 's/("signalingServer":.*").*(")/\1wss:\/\/<domain name>:<port>\2/' /etc/natinst/share/websfpInstrumentInterface.json
    3. Restart the websfpInstrumentIntetface service.
      /etc/init.d/websfpInstrumentInterface restart

If the device is configured correctly, the device ID on the OLED display will start with "XX" and you will be able to see it in the dashboard.

Configure Measurements Live

You must provide the signaling server address to all users of your custom signaling server. Users enter the address in Signaling server address to connect the device to Measurements Live via your custom signaling server.

You can only use secure server address(wss://) in online Measurements Live.

Signaling Server Address in Measurements Live
Advanced Configurations

You can customize your signaling server behaviors by using npm scripts, command-line arguments and the configuration file.

Run the signaling server with an arguments

When you run the signaling server by using npm start, the following command is executed.

node src/app.js -p 1333

You can run the server with a different port by:

node src/app.js -p <port number>

Or view the help of this command by:

node src/app.js -h

Configure the Signaling Server

The following items can be modified through the configuration file: ./config/index.js.

Element Default Value Comment
dataPolicyUrl '' The fully qualified URL of the data policy page associated with the custom signaling server. The built-in data policy page will be used if this value is empty.
apiKey 'Enter your API key' Key string used to restrict access to the signaling server API.
codeGeneration
Element Default Value Comment
prefix 'XX' Prefix that will be included as part of the randomly generated device IDs. Not recommended to exceed 2 characters. Otherwise, the OLED display cannot display the whole ID
allowCustomId false Set to true to allow the device to request a custom device ID instead of always being assigned a randomly generated device ID. If the ID requested is in use by another device, the device will be assigned a randomly generated ID instead.
logLevel 'error' Controls the verbosity of the logging. The available options are 'error', 'info' and 'debug'. 'error' generates the least logging data, and 'debug' generates the most.
host '127.0.0.1' The default host for the signaling server. Use 0.0.0.0 to enable all available IPs.
Change API Key

To improve security, you can use your own API Key to make sure that only your applications (the dashboard) can call the APIs of your signaling server and get the sensitive information.

You can change the API Key value of the signaling server in <package directory>/config/index.js.

After changing the API Key value of the signaling server, you should change the API Key used by your application as well. For the dashboard, change it in <package directory>/dashboard/config.js.

Customize Data Policy

The data use notice is a static webpage which states the data policy. The signaling server retrieves device data (serial number, device ID, MAC address, IP address, Hostname, used hardware and software versions) while the device connects to the server, and it is necessary to inform all users about that.

A user can check your data policy by clicking Data Use Notice in the Device tab of Measurements Live after entering your custom signaling server address.

The signaling server provides a built-in data use notice page by default: ./datapolicy/datapolicy.html. You can edit the file or replace it with your own content.

You can also change the value of dataPolicy in the configuration file to an absolute URL to use a webpage from another location as the data use notice.

Upgrade the Signaling Server Package

To update the signaling server package to the latest released version, navigate to the installation directory first and then update the package by:

npm update --global-style @ni/measurementslive-signalingserver

Note: Updating the package overwrites all files, including the configuration file for signaling server and the configuration file for the dashboard, and the default data policy webpage. Do back up these files before you run the update command.

Deploy the server with pm2

NI recommends using the production process manager pm2 when deploying a signaling server.

The signaling server includes pm2 configurations. See <package directory>/package.json for the preconfigured pm2 commands.

You must install pm2 globally via NPM before using it to monitor the server and its logs:

npm install pm2 -g

Refer to the pm2 documentation for more information.

Start the signaling server with pm2 by:

npm run pm2-run-server

Start the dashboard with pm2 by:

npm run pm2-run-dashboard

Logging

The server uses bunyan for generating logs. bunyan generates JSON log outputs and includes a tool that lets you filter log outputs.

To view the pm2 logs using bunyan, ensure you have bunyan installed globally:

npm install bunyan -g

To view the logs in real-time, use the bunyan filtering:

pm2 logs --raw --name signaling-server | bunyan
Using the APIs of Signaling Server

The dashboard is an example of using signaling server APIs, which are designed to be called via a WebSocket session. You can design your own application to call these APIs for further customization. This document takes JavaScript for browser and node.js as an example, but you can use any programing language that supports WebSocket, for your application.

Your application must open a WebSocket connection to <signaling server address>/api, before any API is called. For example, ws://localhost:1333/api.

let signalingServer = null;
signalingServer = new WebSocket('ws://localhost:1333/api');

Note: In a browser, WebSocket is a predefined class. However, in node.js, you must install ws package and import it as WebSocket first.

const WebSocket = require('ws');

Requests

An API call request is a JSON object. Send a stringified JSON object as payload via the WebSocket session to call an API:

signalingServer.send(JSON.stringify({
	command: '<The command name>',
	apikey: '<The customized API key string>',
}));

For example, you can send an API call request of command devices with API key "xxxxxxxx":

signalingServer.send(JSON.stringify({
	command: 'devices',
	apikey: 'xxxxxxxx',
}));

The command property is required. There are several available API commands: register, devices, datapolicy, and codePrefix.

Some APIs, register, and devices, require a correct API key to be called successfully, since these APIs will provide the sensitive information, such as the IP address of registered devices. The other APIs, datapolicy and codePrefix, do not need any API key.

register

After an application calls the register API, the application will be registered. Signaling server will send the change result messages to all registered applications every five seconds or when any change occurs. In this way, the applications will always get the latest server status information.

Once the application has been successfully registered, the signaling server will respond with a register result message. This API should be called once at most for each WebSocket session, or an error message will be sent.

The change result messages will be sent repeatedly until the WebSocket session is closed:

signalingServer.close();
devices, datapolicy and codePrefix

The signaling server will respond with a result message each time an application calls this API command. The message type is corresponding to the command. Unlike the register command, these APIs can be called for multiple times and only one response for each call. See Results for further information.

Results

An API call result is also a JSON object. All the results are sent as WebSocket message. You must program your application to receive and handle these messages:

signalingServer.addEventListener('message', (p_Event) => {
	let result = null;
	try {
		result = JSON.parse(p_Event.data);
	} catch (e) {
		console.error(e);
	}
	// Code to handle result messages here
}

There are several types of result object: register, devices, datapolicy, codePrefix, change and error, while the change result can be different for several change issues.

register
{ "type": "register", "register": "success" }

Once the application has been successfully registered, the application will receive this result message.

devices
{
	"type": "devices",
	"devices": [
		{
			"id": "XXXXXXXXXX", // The device ID with prefix
			"gracePeriod": 10, // Minutes before a device infomation to be removed from signaling server after it disconnect
			"leaseTime": 4, // Hours before a device's id to be updated automatically
			"name": "NI-ELVIS-III-XXXXXXX",
			"mac": "00:00:00:00:00:00",
			"serialNumber": "0000000",
			"leaseCreated": "2018-01-01T00:00:00Z", // When the current device id is created
			"connectedPeers": 0,
			"upTimeMinutes": 0,
			"details": {
				"apiVersion": "X.X",
				"buildDate": "2018-01-01_00:00:00",
				"command": "getDeviceInformation",
				"description": "NI ELVIS III device description",
				"deviceMake": "National Instruments",
				"deviceModel": "NI ELVIS III",
				"deviceName": "NI-ELVIS-III",
				"errorCode": 0,
				"firmwareVersion": "X.X.XfX",
				"gitHash": "0000000000000000000000000000000000000000",
				"ip4Adresses": [
					{
						"address": "0.0.0.0",
						"interfaceName": "eth0",
						"macaddress": "00:00:00:00:00:00"
					},
					// ...
				],
				"ip6Adresses": [
					// ...
				],
				"serialNumber": "0000000",
				"topBoard": {
					// ...
				},
				"version": "X.X.XfX"
			}
		},
		// ...
	],
	"disconnectedDevices": [
		// ...
	]
}

This result message is corresponding to devices API command. It contains information of all the registered devices of the signaling server.

datapolicy
{ "type": "datapolicy", "url": "<the datapolicy webpage address>" }

This result message is corresponding to datapolicy API command, which can be called without an API key.

codePrefix
{ "type": "codePrefix", "prefix": "XX" }

This result message is corresponding to codePrefix API command, which can be called without an API key.

change - signalingServerStatus
{
	"type": "change",
	"change": "signalingServerStatus",
	"deviceCount": 0, // The number of connected NI ELVIS III devices
	"clientCount": 0, // The number of Measurements Live clients that are trying to connect a device via the signaling server. It won't be large since a client is not counted by signaling server after it connects to the device.
	"platform": "<server OS type>"
	"cpu": 0, // CPU usage
	"cpuCount": 1,
	"totalmem": 1000, // MBs of the signaling server memery 
	"freemem": 100, // MBs of the signaling server free memery
	"systemUptime": 0, // Seconds from the signaling server system start
	"processUptime": 0, // Seconds from the signaling server process start
	"serverDate": 0, // Current time of the signaling server OS in seconds from Jan 1st 1970
	"localVersion": X.X.X, // The server version number from configure file. Same to package version number by default.
	"npmPackageInfo": {
		"currentVersion": "X.X.X", // The version number of the running signaling server package 
		"latestVersion": "X.X.X", // The version number of lastest signaling server package on npm
		"hasUpdate": false // True if there is a newer version of signaling server package available on npm
	}
}

This result message is sent to an application periodically after it calls register API successfully. It contains the latest information about the signaling server itself. It will also be sent to the registered application while a change result for another change issue is sent.

change - deviceUpdate
{
	"type": "change",
	"change": "deviceUpdate",
	"device": {
		"id": "XXXXXXXXXX",
		// ...
	}
}

This result message is sent to all registered applications when any device status changs. For example, when a device is connected or when a device ID is updated. The content of "device" is the same to an element in the "devices" array of the devices result.

change - deviceEntersGracePeriod
{
	"type": "change",
	"change": "deviceEntersGracePeriod",
	"device": {
		"id": "XXXXXXXXXX",
		// ...
	}
}

This result message is sent to all registered applications when a connected device disconnects. The server keeps the device ID and the other information of this device for grace period, in disconnected device list. If the device is reconnected during the grace period, the same device ID will be assigned.

The content of "device" is same to an element in "devices" of the devices result.

change - gracePeriodExpired
{
	"type": "change",
	"change": "gracePeriodExpired",
	"devices": [
		{
			"id": "XXXXXXXXXX",
			"gracePeriod": 10,
			"name": "NI-ELVIS-III-XXXXXXX",
			"serialNumber": "0000000",
		},
		// ...
	]
}

This result message is sent to all registered applications when the grace period of a disconnected device expires. The server does not keep the information of this device afterward. If the device is reconnected after the grace period, it will be registered as a new one and get another device ID.

This message only contains limited information about the disconnected device.

Typical use cases

Using these APIs, you can set up your own application to get the server status and all the connected device information from anywhere. This application provides deeply customized functions, feature and user interface. For example, you may prefer a better server monitor instead of the dashboard example. Students can also get a device ID remotely to do experiments from home.

Note: NI does not recommend lab administrators to allow users to call all the APIs directly. The API key is used to reject improper API calls.

Remote device access

A user needs the device ID to connect Measurements Live to a device via the network. If you want to set up a remote laboratory, you must provide a method to get device ID remotely for the users.

For instance, you can set up a web service application and provide a webpage for the users. The users can send a query request for a device ID via the webpage.

The web application will handle the query requests. It maintains a device list by calling the signaling server APIs. You can also add custom information to tag the devices, such as the experiment circuit name or user groups that have the access right. The application also maintains a database for user accounts.

For example, the application may receive a request as the following:

{ user: John, password: 12345678, circuit-name: low-pass-filter }

Then it checks the account information in the database, searches for a suitable device from the device list and responds to the user with the device ID.

In this way, you can enable the users to get device ID remotely.

Example Code

Run the following piece of JavaScript code in a browser or in node.js to list all the names and the IDs of connected devices from a custom signaling server on the console. The code assumes the server address is "ws://localhost:1333", and the API key is "Enter your API key".

const WebSocket = require('ws'); // This line is only for node.js code
let signalingServer = null;
signalingServer = new WebSocket('ws://localhost:1333/api');
signalingServer.addEventListener('open', () => {
	signalingServer.send(JSON.stringify({
		command: 'devices',
		apikey: 'Enter your API key'
	}));
});
signalingServer.addEventListener('message', (p_Event) => {
	let result = null;
	try	{
		result = JSON.parse(p_Event.data);
	} catch (e) {
		console.error(e);
	}
	if (result.type == 'devices') {
		// The result about device information will be received and be handled here
		console.log(`${result.devices.length} device(s) connected.`);
		result.devices.map((device) => {
			console.log(`Name: ${device.name}, ID: ${device.id}.`);
		});
	}

	signalingServer.close();
});
signalingServer.addEventListener('close', () => {
	signalingServer = null;
});
signalingServer.addEventListener('error', () => {
	signalingServer.close();
});
Setting up STUN Server
Session Traversal Utilities for NAT (STUN) server is used to obtain the public network IP and port number of an application in subnet. The IP and port number are needed to open a connection between NI ELVIS III and the browser. By default, public STUN servers are used.

If there are security/firewall concerns with using public STUN servers, it is possible to set up your own STUN server. Measurements Live has been tested with coturn in a Ubuntu 16.04 LTS environment. Coturn is an open source STUN server that can be installed from the Ubuntu repositories. A brief installation summary is given below. You may need to work with your system administrator for detailed help in configuring your own STUN server and your network environment.

  1. Set up Ubuntu 16.04 LTS (or other compatible Linux)
  2. Run sudo apt-get install coturn
  3. Sample command:
sudo turnserver -a -o -v -n -S -f -u user:root -p 3478 -L INT_IP -r someRealm -X EXT_IP/INT_IP  --no-dtls --no-tls --no_cli
  • -o, run as a daemon
  • -n, only use command-line parameters
  • -S, STUN server only
  • -fingerprint
  • -lt-cred-mech
  • -v, medium level of logging
  • -L Internal IP
  • -X External IP/Internal IP
  • --no-dtls
  • --no-tls
  • --no-cli

For more complete documentation visit the coturn wiki

Downloadable source code to build coturn for your environment can be found at https://github.com/coturn/coturn