Skip to main content

ProGlove Documentation

Connect Gateway Plus using WebSocket

The WebSocket integration path lets you connect the Gateway Plus to your enterprise network. This is done using a network.json file with your network's credentials, and a websocket.json file containing your WebSocket integration settings.

The easiest way is to enter all details directly in the INSIGHT webportal while creating your Device Configuration. This allows you to add and define all the relevant parameters in a single place, and automatically create fully functional files that are ready for immediate use. You can then apply the configuration by transferring the files to your Gateway Plus device, or using the option INSIGHT offers and applying your configuration by simply scanning a custom QR code.

If you prefer the manual process, you can still create your own network.json and websocket.json files and add any relevant details using the main fields and examples provided below. Zip both files with any required certificates together in a .zip archive file, and upload it to your Gateway Plus as a mass storage device.

Note

Read more about uploading files to the Gateway Plus while in Mass storage mode.

Example 32. Example of the provision.zip file structure

  • provision.zip

    • websocket.json

    • network.json

    • File 1 (e.g., ca_cert.pem )*

    • File 2 (e.g.,cert.pem)*

    • File 3 (e.g., key.pem)*

*This is required only for self-signed certificates or certificates that were signed by an unrecognized authority.



WebSocket.json file configuration

To configure the WebSocket integration, add relevant information to the websocket_client namespace using the fields described below. For a better understanding of how to configure the websocket.json fields, see examples.

Create the websocket.json file

  1. Open a text editor (E.g. Notepad, Sublime Text, VS Code)

  2. Copy the snippet below into the editor.

    {
    "websocket_client": {
        "domain": "proglove.de"
    }
}

  3. Under domain, type in the URL or the IP address of the server you want to connect to.

  4. Save the file as websocket.json.

Note

For additional configuration, see the fields below.

Apply the websocket.json file

  1. Connect the USB cable of your Gateway Plus device to your desktop.

    The Gateway Plus boots up in about 1 minute. The Power and Data LEDs on the Gateway Plus glow green constantly.

  2. Scan the barcode on the Gateway Plus with your scanner.

    The scanner connects to your Gateway Plus and the Scanner LED on the Gateway Plus glows green.

  3. Scan the barcode below to enable the Gateway Plus as a mass storage device.

    PEP_EnableMassStorage.png

    The Gateway Plus displays as a mass storage device on your desktop.

  4. Upload the zipped websocket.json file to your Gateway Plus.

    Note

    If the Gateway Plus is not connected to the network, upload the zipped network.json file too.

  5. Eject the Gateway Plus as a mass storage device from your desktop.

    The upload takes a few seconds. All four LEDs flash green when done. The Gateway Plus automatically connects to your network and INSIGHT, and the Cloud LED on the Gateway Plus glows green.

Note

Ejecting a mass storage device may vary depending on your operating system.

Make sure to use the Safely Remove Hardware / Eject Media option to remove the Gateway Plus as the mass storage device on your desktop but do NOT disconnect the USB cable of your Gateway Plus during upload.

Main fields

Field

Type

Description

Required

Default

protocol

object (see Protocol)

Use the protocol to connect to the server (plaintext or encrypted with SSL).

This defines which protocol the Gateway Plus will use: ws:// for plaintext or wss:// for SSL.

No

Plaintext

domain

string

The domain or address of the server. (e.g., 192.168.0.1 or proglove.de.)

Yes

/

path

string

The path on the server serving the WebSocket.

No

/

port

integer

The port number to connect to the server.

No

80 if using plaintext or 443 if using SSL.

credentials

object (see Credentials)

The credentials to use in case the connection requires an authentication.

No

/

Protocol

Field

Type

Description

plaintext

object

Uses plaintext to talk to the server.

ssl

object (see SSL)

Uses an encrypted connection with SSL to talk to the server.

SSL

Field

Type

Description

basic_auth

object (see Basic authentication)

Authenticate with the server using basic authentication.

ca_cert_path

string

The path to the Root Certificate Authority file in the archive.*

*This is required only for self-signed certificates or certificates that were signed by an unrecognized authority.

Credentials

Field

Type

Description

basic_auth

object (see Basic authentication)

Authenticate with the server using basic authentication.

Basic authentication

Field

Type

Description

Required

username

string

The username used to authenticate with the server.

Yes

password

string

The password used to authenticate with the server.

Yes

Examples
Unencrypted

The examples in this section describe how to connect using an unencrypted connection.

Simple unencrypted connection

Connect to a WebSocket server on port 80 at address proglove.de on path /.

WebSocket URI: ws://proglove.de:80/

{
	"websocket_client": {
		"domain": "proglove.de"
	}
}
Unencrypted connection with specific path and port

Connect to a WebSocket server on port 4242 at address proglove.de on path /websocket.

WebSocket URI: ws://proglove.de:4242/websocket

{
	"websocket_client": {
		"domain": "proglove.de",
		"port": 4242,
		"path": "/websocket"
	}
}
Encrypted
Encrypted connection with default settings.

Connect to an encrypted WebSocket server on port 443 at address proglove.de on path /.

WebSocket URI: wss://proglove.de:443/

{
	"websocket_client": {
		"domain": "proglove.de",
		"protocol": {
			"ssl": {
			}
		}
	}
}
Encrypted connection with specific path and port

Connect to an encrypted WebSocket server on port 4242 at address proglove.de on path /websocket.

WebSocket URI: wss://proglove.de:4242/websocket

{
	"websocket_client": {
		"domain": "proglove.de",
		"port": 4242,
		"path": "/websocket",
		"protocol": {
			"ssl": {
			}
		}
	}
}
Encrypted connection with a root certificate

Connect to an encrypted WebSocket server on port 443 at address proglove.de on path / using a root certificate located at ca.pem* in the archive.

*This is required only for self-signed certificates or certificates that were signed by an unrecognized authority.

WebSocket URI: wss://proglove.de:443/

{
	"websocket_client": {
		"domain": "proglove.de",
		"port": 4242,
		"path": "/websocket",
		"protocol": {
			"ssl": {
				"ca_cert_path": "ca.pem"
			}
		}
	}
}
Basic Authentication
Simple unencrypted connection with credentials

Connect to a WebSocket server on port 80 at address proglove.de on path / using Basic Authentication with username foo and password bar.

WebSocket URI: ws://foo:bar@proglove.de:80/

{
	"websocket_client": {
		"domain": "proglove.de",
		"credentials": {
			"basic_auth": {
				"username": "foo",
				"password": "bar"
			}
		}
	}
}
Encrypted connection with credentials

Connect to a WebSocket server on port 443 at address proglove.de on path / using Basic Authentication with username foo and password bar.

WebSocket URI: wss://foo:bar@proglove.de:443/

{
	"websocket_client": {
		"domain": "proglove.de",
		"credentials": {
			"basic_auth": {
				"username": "foo",
				"password": "bar"
			}
		},
		"protocol": {
			"ssl": {
			}
		}
	}
}
In this section: