Internal

• 1: REST API
• 2: Virtual Core
• 3: XML File Output
• 4: Timer
• 5: Dummy
• 6: Keyboard

1 - REST API

Configuration

On the General tab, the following settings are available:

HTTP Server

• Port: The default port number is 17011.
• Bind IP: Enter an IP adress here to bind to a specific local interface. Default is to listen on all interfaces.
• Document Root: The root folder for the file hosting feature (see below).

Authentication

The HTTP server supports optional authentication, either through HTTP Basic Auth (username and password), or HTTP Bearer Auth (using a base64-encoded bearer token).

If both username/password and token are set, you can any of these to access the server.

WebSocket

Here you can enter an optional list of filters (as regular expressions) for the WebSocket notifications (see below).

Parameters

The REST API connection does not expose any parameters.

Endpoints

The REST API provides the following HTTP endpoints:

Parameters

The current value of a parameter can be queried with:

GET /parameters/<Connection ID>/<Parameter ID>

e.g.

GET /parameters/dhd-studio1/logic/87

If you set the Accept header to application/json, the value will be encoded as a JSON value (string, number, or boolean). Otherwise it will be sent as a plain string.

If the state of the parameter is currently unknown, you will receive a 503 State Unknown reply.

Parameters can be updated with a request to

GET /update

or

POST /update    

It expects two parameters in the GET request (or POST body):

parameter=<Connection ID>/<Parameter ID>
value=<new value>

Values are always encoded as a string and will be typecasted to the correct value type automatically.

WebSockets

The REST API provides a WebSocket endpoint under /ws which can be used to receive incoming parameter updates in realtime.

Notifications are sent as JSON objects of the following form:

{
  p: "<Connection ID>/<Parameter ID>",
  v: "<new value>"
}

In order to keep traffic as low as possible, you can limit the parameters to specific subtrees in the configuration.

Parameters can also be updated through the WebSocket connection by sending back JSON objects of the same form. The v part of the object can also be any other JSON type (not just string) and will be converted automatically.

File Hosting

The REST API server can also act as a regular web server, hosting static HTML and other files.

To enable this feature, copy all content to a folder of your choice, and set it as the Document Root in the configuration.

The files will be served directly under the main / directory of the service. You cannot host any files with names that conflict with the built-in endpoints (/ws, /parameters, etc.).

2 - Virtual Core

3 - XML File Output

4 - Timer

This connection type provides timers and pulses.

Timers are started by sending any value to their start parameter. If the value is a number, it will be used as the duration (in milliseconds), otherwise the default duration set in the configuration will be used. When the specified time has elapsed, the trigger parameter will send a Trigger value.

Pulses continuously send triggers in fixed intervals.

Configuration

Timers

Each Timer connection provides up to 16 timers. For each timer, you can adjust the duration after which its trigger parameter is triggered (unless a specific duration is sent to the start parameter). The default is 1000 milliseconds.

Pulses

You can define up to 16 pulses. Check the Enabled box for those pulses that you intend to use, and adjust the duration (in milliseconds) as required.

Parameters

• timer/<id>/start (integer, write-only) - Set to a number to start the timer with the specified duration in milliseconds. If you connect this to a boolean or trigger parameter in the Protocol Converter, the timer will be started with the default duration set in the configuration.
• timer/<id>/trigger (trigger, read-only) - will be triggered as soon as the duration has elapsed after starting the timer with start.
• pulse/<id> (trigger, read-only) - will be triggered periodically according to the interval set in the configuaration.

5 - Dummy

The Dummy connection provides an arbitrary number of user-definable parameters which can be used as intermediate storage.

Configuration

On the Parameters tab, enter the list of parameters you wish to define, one parameter per line, in the following form:

<Parameter ID>[,<Value Type>[,<Default Value>]]

The Parameter ID must follow the syntax rules for valid parameter ID; in particular, it can use the / sign to build hierachies/trees.

The Value Type can be one of S (string). B (boolean), I (integer), F (float) or T (trigger). The default value type is string.

The parameter will be set to the Default Value, if specified, when the connection starts. If no default value is given, its value will be undefined until it is set manually or from a Protocol Converter rule or any API (e.g. MQTT Bridge).

Parameters

The connection will expose the parameters defined in the configuration. All parameters are read-write, and of the type specified in the configuration.

6 - Keyboard

This connection type provides two things:

• “Input keys” - system-wide hotkeys represented by read-only trigger parameters.
• “Output keys” - write-only trigger parameters that simulate a keystroke on your computer.

Configuration

Input Keys

On the Input Keys tab, enter one or more keys (or key combinations) that should be available as hotkeys.

You can specify the keys manually (such as ctrl-f1), or use the input field at the bottom of the tab, press the desired key combination, and then click Add to add it to the list.

Note that all hotkeys will be global, i.e., the will be available regardless of whether the application is in the foreground or not. As a consequence, the keys combinations will not be available in any other application anymore.

Output Keys

On the Output Keys tab, enter one or more key combinations that you intend to use as virtual keys, triggered by a parameter (see below).

Again, you can use the input field and the Add button to conviently add the desired key combinations.

Parameters

• input/<key combination> (trigger, read-only) - Will be triggered when the respective key (combination) is pressed by the user. Due to limitations imposed by Windows, the parameter will not be triggered until the user releases the key(s) again.
• output/<key combination> (trigger, write-only) - Trigger this parameter to virtually “press” the key combination.