[deutsch]

Serial communication

Many measurement and control tasks can be automated by accessing lab devices remotely. A common interface offered by many devices is the serial port, which allows for bidirectional communication between the device and your computer.

Current web browsers do not provide means to use the serial communication directly from JavaScript. If you wish to communicate with serial devices from your browser using JavaScript, you need to use a proxy server that brokers the communication between the browser and the serial device. The Kontrast HTTP server provides such a functionality.

Browser http://localhost:8000/ with your JS code
WebSocket
⟷
over HTTP
Kontrast HTTP server
⟷
Serial device(s)connected via USB/RS232

Configuration

The configuration is specified using the serial property within the Kontrast HTTP server configuration file (as introduced in the Kontrast HTTP server documentation). An example configuration which is used in this article is shown below:

By default, any serial communication capabilities of Kontrast HTTP server are disabled. They can be enabled by setting the Boolean property enabled to true.

The alias property defines the URL prefix at which all registered serial devices can be accessed and managed. The alias must be a string value that starts with a forward slash. Using the configuration from the example above, the URL http://localhost:8000/serial/ will provide an overview in JSON format over all registered serial devices (detailed in the next paragraph). This URL is also the base URL for any device-specific access.

Each serial device that should be accessible using the HTTP server must be explicitly added to the deviceList array. In the above example, one device is added, meaning that the array has one item. The device is given a unique name using the name property. This name will be used as an identifier for the device, independent of the device name given by the operating system (OS). This means that your JavaScript code that communicates with serial devices works independent of OS-specific names.

In the above example, the device is called thermometer, which means that you can access device information (again in JSON format) using the URL http://localhost:8000/serial/thermometer.

You need to link the device with the actual, OS-specific device name using one of the properties windows, macos, linux or freebsd. This OS-specific information is only strictly required for the OS currently used; the configuration for other operating systems is optional and may be omitted.

The deviceName property is the OS-dependent name of the device:

Using serial devices from JavaScript

Querying the serial device state

You can send a HTTP GET request to query the serial device:

If the device is closed, the response will be something like:

If the device was already opened, the response will be something like:

Opening and closing a serial device

You can send a HTTP POST request to open the serial device with the settings specified in the request body:

You can send a HTTP DELETE request to close the serial device:

Modifying serial device settings

You can send a HTTP PATCH request to change the serial device settings as specified in the request body:

Starting a WebSocket connection with a serial device

You can establish a WebSocket connection with an opened serial device. The protocol (specified in the second parameter of the WebSocket constructor) must be either khs-serial-read in order to read data from the serial device or khs-serial-readwrite for read and write access. In both cases, data can be sent as a binary message using the send command of the WebSocket and you can read data by listening to the 'message' callback of the WebSocket.

The first example simply logs the data from the serial device (as an ArrayBuffer) to the console:

The second example is the same as the first example with the difference that the data from the serial connection is displayed as text, using a TextDecoder:

The next example sends data to the serial device. Data always needs to be sent as a binary buffer. String values can be converted using a TextEncoder:

A full example that builds upon the above described primitives for receiving and sending data is shown in the Example: Serial console.

Delimiter-based communication

Note that all above examples receive data from the serial connection in their raw from, i.e., as the operating system provides them. This gives you utmost flexibility in using this data. However, a common application is a text-based communication where each message from and to the device is delimited by a predefined character, such as a newline character.

In the utilities/ directory we provide a serial.js helper library that buffers incoming data until the delimiter character is transmitted. This library is used in Example: Serial communication with callbacks and Example: Serial communication with promises using two different programming styles (callbacks and promises, respectively).

Serial device configuration

Please read the serial terms and definitions for details on the properties below and how to find out the specific settings for your device.

You can omit any of the above properties when performing a HTTP POST or PATCH request. In that case, the setting is left unchanged.

Examples