This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Generic

1 - HTTP Client

This protocol allows you to fetch data from an HTTP server using GET requests.

Supported Devices and Prerequisites

The HTTP Client connection can fetch data from any HTTP or HTTPS URL.

Optionally, basic authentication or bearer authentication (token) is supported.

Configuration

The following configuration settings are available:

Server configuration:

  • URL: This is the URL that the HTTP GET request is performed on.
  • Auth User and Auth Password: Fill in values here if your server requires HTTP Basic authentication.
  • Auth Token: Enter an optional token if your server uses HTTP Bearer authentication.

Options:

  • Polling Interval: Enter the interval (in milliseconds) between two HTTP calls. The default is 5000 milliseconds (five seconds).
  • Enable Polling: Uncheck to disable automatic polling. In this case, the HTTP request will only be performed when the trigger parameter is used (see below).
  • Parse Mode: Select the desired mode in which the content returned by the server is parsed (or not). The currently supported modes are None and JSON. See the Parameters section below for details.

Parameters

A write-only trigger parameter is provided which can be used to manaully trigger an HTTP call, whether or not periodic polling is enabled. When automatic polling is disabled, this is the only way to fetch HTTP data from the server.

The received data is provided under in data part of the parameter tree. It depends on the parsing mode set in the configuration:

No Parsing

In parsing mode None, the data returned from the server is exposed as a single read-only string parameter data.

JSON Parsing

In parsing mode JSON, the returned document is considered a JSON document (regardless of the Content-type returned by the server), and it is parsed into a parameter tree (with data as the root) that corresponds to the JSON document.

Any kind of JSON value (object, array, string, number, boolean) is supported at any level of the tree.

  • JSON strings will be turned into string parameters.
  • JSON booleans will be turned into boolean parameters.
  • JSON numbers will be turned into integer or float parameters, depending on whether the number is a whole number or not.
  • JSON objects will be turned into sub-trees.
  • JSON arrays will be turned into indexes subtrees, starting with 0.

For example, the following JSON document

{ 
	"event": "meeting",
	"room": 12,
	"people": [
		{
			"first_name": "Joe",
			"last_name": "Smith",
		},
		{
			"first_name": "Mary",
			"last_name": "Miller",
		}
	]
}

will be translated into these parameters and values:

  • data/event (string): meeting
  • data/room (integer): 12
  • data/people/0/first_name (string): Joe
  • data/people/0/last_name (string): Smith
  • data/people/1/first_name (string): Mary
  • data/people/1/last_name (string): Miller

All parameters are read-only.

2 - MQTT Client

This protocol connects to an MQTT broker and allows you to subscribe to and publish MQTT topics as parameters.

Supported Devices and Prerequisites

The MQTT Client can connect to any MQTT broker that supports plain TCP or SSL/TLS connections.

Optional username/password authentication is supported.

Configuration

Network settings:

  • Host: The hostname or IP address of the MQTT broker.
  • Port: The port number to connect to. The default is 1883 (the standard MQTT port). For SSL/TLS connections the typical port is 8883.
  • Use SSL: Check this option to connect using SSL/TLS encryption.
  • Client ID: The MQTT client identifier sent to the broker. Each client connecting to a broker must use a unique client ID. If left empty, the broker may assign one automatically.
  • User and Password: Fill in values here if your broker requires authentication.

Topics:

  • Subscribed Topics: Enter one topic filter per line. The connection will subscribe to these topics on the broker, and incoming messages will be exposed as readable parameters. Standard MQTT wildcard characters (+ for a single level, # for multiple levels) are supported.
  • Published Topics: Enter one exact topic per line. These topics will be exposed as writable parameters, and writing to them will publish a message to the broker. Wildcard characters are not allowed here.
  • Allow Any Publish: If enabled, BTConnect will publish to any valid MQTT topic that is written to, not just the topics listed under Published Topics. This is useful when the target topic is determined dynamically at runtime via converter rules.

If a topic appears in both Subscribed Topics and Published Topics, the corresponding parameter will be both readable and writable.

The connection will automatically attempt to reconnect to the broker every five seconds if the connection is lost.

Parameters

Each configured topic becomes a string parameter in the parameter tree. The parameter path matches the topic name exactly.

Parameter access depends on where the topic is configured:

  • Topics listed only in Subscribed Topics: read-only — updated when a message is received from the broker.
  • Topics listed only in Published Topics: write-only — writing the parameter publishes a message to the broker.
  • Topics listed in both: read/write.

All parameter values are strings. Incoming message payloads are decoded as UTF-8.