Network Server Guide

Introduction

The Phidget Network Server is a powerful tool that allows you to do the following:

• Access Phidgets that are connected to other computers on your network.
• Access Phidgets from more than one application simultaneously.
• Host webpages and run JavaScript applications using the built-in web server.
• Manage dictionaries to easily share information between applications.

This guide will provide an overview of the Phidget Network Server and showcase how it can be used in your applications.

How It Works

The Phidget Network Server has three elements: a Phidget server, a web server, and a dictionary manager. The Phidget server is the primary component, which we will discuss here. The other components will be discussed later in this guide.

When the Phidget Network Server is running, your computer can host a Phidget server which makes all connected Phidget channels available to other computers on your network.

As long as the Phidget server is running, clients can access the remote channels. They can be addressed, opened, and attached in much the same way as local channels.

Unlike local channels, remote channels may be opened by multiple programs simultaneously. There are some exceptions (e.g. motor controllers) that cannot be opened simultaneously for safety reasons.

Hosts and Clients

This guide references host computers and client computers.

• Host: a computer or Wireless VINT Hub that is physically connected to Phidget devices and is running the Phidget Network Server.
• Client: a computer running an application that accesses Phidget channels via the Phidget Server. The Phidget Network Server does not need to run on the client computer.

A single computer can act as both a host and a client. A Wireless VINT Hub (HUB5000) can only act as a host.

Running the Phidget Network Server

On Windows machines, start by installing our libraries. Next, open the Phidget Control Panel on your host computer and navigate to the Network Server tab:

There are various configuration settings for the Phidget Network Server. For now, press Start in the bottom right corner and navigate back to the Phidgets tab.

As shown above, the Phidget server is now making your channels available to other computers on your network. You can view/hide remote channels in the Phidget Control Panel by navigating to File > Options > List Remote Phidgets.

On macOS machines, start by installing our libraries. Next, open the Phidget Control Panel on your host computer and navigate to the Network Server tab:

There are various configuration settings for the Phidget Network Server. For now, press Start at the top of the screen and navigate back to the Phidgets tab.

As shown above, the Phidget Server is now making your channels available to other computers on your network.

On Linux machines, start by installing our libraries, specifically phidget22networkserver and phidget22admin. The Phidget Network Server will start automatically after installing from packages.

Open the terminal on the client and type in the following command:

phidget22admin -s

This will list all of the Phidget servers on your network. Confirm that you can see a Phidget server running on your host computer.

After you have confirmed your server is running, type in the following command:

phidget22admin -R -d

This command will list all remote Phidgets on the network. Confirm that you can see the Phidgets attached to your host computer:

The Wireless VINT Hub will automatically run the Phidget Network Server on boot. No configuration is required. Please note that The Wireless VINT Hub is not able to manage dictionaries.

The PhidgetSBC4 comes with the Phidget Network Server installed, and the SBC automatically starts the Phidget Network Server on boot. Open the web interface and navigate to Phidgets > phidget22Network Server to see the status.

Connecting to Remote Phidgets

After you have the Phidget Network Server running, you can access remote Phidget channels from a client computer.

Networking API

To access remote channels in your application, you will need to use our Networking API. Navigate to our API and select Networking from the dropdown menu.

Here you will see all relevant methods and events. There are two primary ways to connect to remote channels in your application:

1. Specify hostname/IP address (recommended)
2. Enable server discovery

Continue reading for more information.

Connecting via Hostname/IP Address (Recommended)

Specifying a hostname or IP address in your code is recommended for most applications. Examples of how to do this in various languages are shown below:

from Phidget22.Net import *

Net.addServer("ServerName", "hostname/IP address", 5661, "password", 0)

Net.addServer("ServerName", "hostname/IP address", 5661, "password", 0);

Net.AddServer("ServerName", "hostname/IP address", 5661, "password", 0);

PhidgetNet_addServer("ServerName", "hostname/IP address", 5661, "password", 0);

const conn = new phidget22.NetworkConnection(5661, "hostname")
await conn.connect()

Hostname vs IP Address

For most applications, using a hostname to add a server is preferred (such as 'localhost' or 'hub5000.local'). This approach allows your application to adapt seamlessly to network changes. However, in certain scenarios, assigning a static IP address to your host may provide additional benefits.

Enabling Server Discovery

By enabling server discovery, you can access any Phidget server on your network that is published (see Phidget server settings for more information about publishing). Examples of how to do this in various languages are shown below:

Net.enableServerDiscovery(PhidgetServerType.PHIDGETSERVER_DEVICEREMOTE)

Net.enableServerDiscovery(ServerType.DEVICE_REMOTE);

Net.EnableServerDiscovery(ServerType.DeviceRemote);

PhidgetNet_enableServerDiscovery(PHIDGETSERVER_DEVICEREMOTE);

Server discovery is not available in JavaScript due to networking restrictions.

Considerations

Enabling server discovery is useful for certain applications. For example, if you need to manage a dynamic list of devices, similar to the Phidget Control Panel. It can also be useful during development, when devices and networks are changing frequently. For most applications and when deploying applications, connecting via hostname/IP address is recommended.

When using server discovery, review the following:

• A Phidget server must be published in order to connect to it.
• Windows machines must have Bonjour installed on both the host computer and the client computer. Download it here.
• Linux machines require Avahi which is typically preinstalled. It can also be easily installed with apt install avahi-client
• macOS machines require Bonjour which is always preinstalled, so no further configuration is required.

Code Samples

In this example, a Light Phidget (LUX1000) is plugged into a Wireless VINT Hub (HUB5000) which runs the Phidget Network Server. On a client machine, this code is used to remotely access the light sensor and sample 5 seconds of data.

from Phidget22.Phidget import *
from Phidget22.Net import *
from Phidget22.Devices.LightSensor import *
import time

def onIlluminanceChange(self, illuminance):
	print("Illuminance: " + str(illuminance))

def main():
	Net.addServer("PHIDGETS-PC", "hub5000.local", 5661, "", 0);

	lightSensor0 = LightSensor()

	lightSensor0.setIsRemote(True)
	lightSensor0.setDeviceSerialNumber(37299)

	lightSensor0.setOnIlluminanceChangeHandler(onIlluminanceChange)

	lightSensor0.openWaitForAttachment(20000)

	time.sleep(5)

	lightSensor0.close()

main()

import com.phidget22.*;
import java.lang.InterruptedException;

public class Java_Example {

	public static void main(String[] args) throws Exception {
		Net.addServer("PHIDGETS-PC", "hub5000.local", 5661, "", 0);

		LightSensor lightSensor0 = new LightSensor();

		lightSensor0.setIsRemote(true);
		lightSensor0.setDeviceSerialNumber(37299);

		lightSensor0.addIlluminanceChangeListener(new LightSensorIlluminanceChangeListener() {
			public void onIlluminanceChange(LightSensorIlluminanceChangeEvent e) {
				System.out.println("Illuminance: " + e.getIlluminance());
			}
		});

		lightSensor0.open(20000);

		Thread.sleep(5000);

		lightSensor0.close();
	}
}

using System;
using Phidget22;

namespace ConsoleApplication
{
	class Program
	{

		private static void LightSensor0_IlluminanceChange(object sender, Phidget22.Events.LightSensorIlluminanceChangeEventArgs e)
		{
			Console.WriteLine("Illuminance: " + e.Illuminance);
		}

		static void Main(string[] args)
		{
			Net.AddServer("PHIDGETS-PC", "hub5000.local", 5661, "", 0);

			LightSensor lightSensor0 = new LightSensor();

			lightSensor0.IsRemote = true;
			lightSensor0.DeviceSerialNumber = 37299;

			lightSensor0.IlluminanceChange += LightSensor0_IlluminanceChange;

			lightSensor0.Open(20000);

			System.Threading.Thread.Sleep(5000);

			lightSensor0.Close();
		}
	}
}

#include <phidget22.h>
#include <stdio.h>
/* Determine if we are on Windows of Unix */
#ifdef WIN32
#include <windows.h>
#else
#include <unistd.h>
#define Sleep(x) usleep((x) * 1000)
#endif

static void CCONV onIlluminanceChange(PhidgetLightSensorHandle ch, void * ctx, double illuminance) {
	printf("Illuminance: %lf\n", illuminance);
}

int main() {
	PhidgetLightSensorHandle lightSensor0;

	PhidgetNet_addServer("PHIDGETS-PC", "hub5000.local", 5661, "", 0);

	PhidgetLightSensor_create(&lightSensor0);

	Phidget_setIsRemote((PhidgetHandle)lightSensor0, 1);
	Phidget_setDeviceSerialNumber((PhidgetHandle)lightSensor0, 37299);

	PhidgetLightSensor_setOnIlluminanceChangeHandler(lightSensor0, onIlluminanceChange, NULL);

	Phidget_openWaitForAttachment((PhidgetHandle)lightSensor0, 20000);

	Sleep(5000);

	Phidget_close((PhidgetHandle)lightSensor0);

	PhidgetLightSensor_delete(&lightSensor0);
}

const phidget22 = require('phidget22');

async function runExample() {
	const conn = new phidget22.NetworkConnection(5661, 'hub5000.local');
	try {
		await conn.connect();
	} catch(err) {
		console.error('Error during connect', err);
		process.exit(1);
	}

	const lightSensor0 = new phidget22.LightSensor();

	lightSensor0.setDeviceSerialNumber(37299);

	lightSensor0.onIlluminanceChange = (illuminance) => {
		console.log('Illuminance: ' + illuminance.toString());
	};

	try {
		await lightSensor0.open(5000);
	} catch(err) {
		console.error('Error during open', err);
		process.exit(1);
	}

	setTimeout(async () => {
		await lightSensor0.close();
		conn.close();
		conn.delete();
	}, 5000);
}

runExample();

Code Sample Generator

The code sample above was generated using our Code Sample Generator. To generate Network-enabled code for a specific device, select the Remote checkbox and specify a hostname.

Webserver

The Phidget Network Server includes a built-in web server and is required for supporting the Phidget JavaScript library for in-browser use.

• On Windows and macOS, a JavaScript version of the Phidget Control panel is served on port 8989 (http://localhost:8989) by default.
• On Linux machines, PhidgetSBC4, and the Wireless VINT Hub, a JavaScript version of the Phidget Control panel is served on port 8080 (http://localhost:8080) by default.

Enabling the Webserver

On Windows and macOS, you can enable the web server through the Phidget Control Panel:

On Linux, you can enable it in the Phidget Network Server configuration file located at /etc/phidgets/phidget22networkserver.pc. Modify enabled to true in the www section.

Considerations

The primary purpose of the Webserver is to support a Websockets connection for the in-browser JavaScript library - because regular sockets cannot be used in-browser.

Dictionaries

The Phidget Network Server allows you to publish Phidget Dictionaries on your network. Dictionaries provide a convenient method of sharing information between applications. For more information, view our Phidget Dictionaries Guide.

Upgrading the Phidget Network Server

From time to time, you may consider upgrading your Phidget Network Server (i.e. your Phidget libraries). There are several reasons to do this, for example:

• Your application needs to support a new device.
• The Phidget22 Changelog indicates that there was an improvement or bug fix that is relevant to your application. Consider signing up for Phidget22 Changelog notifications to stay updated.

When upgrading your Phidget libraries, you should ensure your host and client are on the same version for the best performance.

Host: Determining Version

Select the operating system of your host for more information.

On Windows, the Phidget Network Server is managed from the Phidget Control Panel. Open the Phidget Control Panel and navigate to Help > About Phidget Control Panel to see the library version you are running.

On macOS, the Phidget Network Server is managed from the Phidget Control Panel. Open the Phidget Control Panel and navigate to Phidget Control Panel > About Phidget Control Panel to see the library version you are running.

On Linux, open a terminal and enter the following command

apt show libphidget22

On the Wireless VINT Hub (HUB5000), navigate to the web interface, select the Phidgets tab, and then select the View button.

You will now see the Phidget log. At the top of the file, you will see the library version:

On the PhidgetSBC, navigate to the web interface and select the Status > System tab.

Client: Determining Version

There are several ways to determine the version of the Phidget library used in your application. Below are some recommended methods.

Phidget Logging

If you have Phidget Logging enabled in your application (recommended), you can view the library version that your project is using at the top of the log file.

Phidget API

The Phidget API makes it easy to verify the version of the Phidget libraries that your application is using. View the code samples below for more information.

from Phidget22.Phidget import *
from Phidget22.Devices.VoltageInput import *

libraryVersion = Phidget.getLibraryVersion()
print("LibraryVersion: " + str(libraryVersion))

import com.phidget22.*;

class Example {
	public static void main(String[] args) {
		try {
			java.lang.String LibraryVersion = Phidget.getLibraryVersion();
		} catch (PhidgetException ex) {
			System.out.println("Failure: " + ex);
		}
	}
}

using System;
using Phidget22;

class Program {
	static void Main(string[] args) {
		try {
			string LibraryVersion = Phidget.LibraryVersion;
		} catch (PhidgetException ex) {
			Console.WriteLine("Failure: " + ex.Message);
		}
	}
}

int main() {
	PhidgetReturnCode res;
	const char *libraryVersion;

	res = Phidget_getLibraryVersion(&libraryVersion);
	if (res != EPHIDGET_OK)
		return 1; // Exit in error

	return 0;
}

// NOTE: This shows importing phidget22 in Node.JS. In-Browser JavaScript import is different
const phidget22 = require("phidget22");

async function main() {
	const libraryVersion = Phidget.libraryVersion;
	console.log("libraryVersion: " + libraryVersion);

}

main();

Phidget Network Server Logging

The host computer will generate a Phidget Network Server log file. Select the operating system of your host below for information about where this log file can be found.

On Windows, the Phidget Network Server log file is located at:

C:\ProgramData\Phidgets\logs\Phidget22NetworkServer_networkserver.log

You can also navigate here by opening the Phidget Control Panel an selecting Help > Open Logs Folder.

On macOS, the Phidget Network Server log file is located at:

/Library/Logs/phidget22networkserver.log

On Linux, the Phidget Network Server log file is located at:

/var/log/phidget22networkserver.log

On the Wireless VINT Hub (HUB5000), open the web interface and navigate to the Phidgets tab. Select the View button to view the log file.

On the PhidgetSBC4, the Phidget Network Server log file is located at:

/var/log/phidget22networkserver.log

Phidget Network Server Settings

Operating System

There are a number of settings related to the Phidget Network Server. Select your operating system for more information about how to modify these settings.

On Windows, you can adjust settings by opening the Phidget Control Panel and navigating to the Network Server tab.

On macOS, you can adjust settings by opening the Phidget Control Panel and navigating to the Network Server tab.

On Linux, you can adjust settings by navigating to the network server configuration file located at /etc/phidgets/phidget22networkserver.pc.

On the Wireless VINT Hub (HUB5000), you can adjust settings through the web interface by navigating to the Phidgets tab.

On the PhidgetSBC, you can adjust settings through the web interface by navigating to the Phidgets Tab and then the phidget22 Network Server tab.

Basic Settings

Startup Type

Setting	Description
Automatic	The Phidget Network Server will start automatically every time your machine boots.
Manual	The Phidget Network Server needs to be started manually. It will not restart when your machine boots. Another service may also start it when in Manual mode.
Disabled	The Phidget Network Server is disabled. This will disable all components, including the Phidget Server, the Webserver, and any Dictionaries. Other services will not be able to start it.

Phidget Server

Setting	Description
Enabled	Enables the Phidget Server. When enabled, client computers on your network will be able to access Phidgets that are connected to your computer.
Publish	This will determine if the Phidget Server should publish itself to mDNS. If you plan to use the EnableServerDiscovery method in your applications, you must publish your Phidget Server. Otherwise, this can be disabled.
Server Name	Specify the name of your server. A setServerName method is available when addressing your channels. If you plan to use the EnableServerDiscovery method in your applications, the Server Name can be used to enable or disable servers. The default server name is the computer name (hostname on Linux machines, Wireless VINT Hub, and PhidgetSBC4). This means if you do not specify a server name, your server name may change if your change your computer name or hostname.
Port	Specify the Phidget server port. Defaults to 5661.
Password (optional)	This will determine if a password is required to access channels on the Phidget server.
Log Level	When running, the Phidget Network Server will generate logs. Use these options to configure the log level. Defaults to Info.

Webserver

Setting	Description
Enabled	Enables the web server. The web server enables connections from the in-browser JavaScript library and allows hosting of files.
Port	Specify the web server port. Defaults to 8989.
Docroot	Specify the location of your web server files.

Dictionaries

Setting	Description
Enabled User Dictionaries	Enables user dictionaries. These are useful for sharing information between applications.
Enable Monitoring/control Dictionary	Enables a monitoring/control dictionary that provides information about incoming/outgoing traffic related to your Phidget Network Server.

For more information about dictionaries, view our Phidget Dictionaries Guide.

Advanced Settings

Advanced settings are available through a configuration file. Select the operating system of your host below for more information.

For advanced settings, you can edit the configuration file directly by navigating to C:\ProgramData\Phidgets\phidget22networkserver.pc. Refer to the Phidget Network Server Linux README for more information.

For advanced settings, you can edit the configuration file directly by navigating to /Library/Preferences/Phidget22NetworkServer/phidget22networkserver.pc. Refer to the Phidget Network Server Linux README for more information.

On Linux, you can adjust settings by navigating to the network server configuration file located at /etc/phidgets/phidget22networkserver.pc. Refer to the Phidget Network Server Linux README for more information.

You can also point the Phidget Network Server towards your own configuration file with the following command:

phidget22networkserver -c /path/to/configuration/file

Advanced settings are not available on the Wireless VINT Hub.

For advanced settings, you can edit the configuration file directly by navigating to /etc/phidgets/phidget22networkserver.pc. Refer to the Phidget Network Server Linux README for more information.