Concepts

• 1: Connections
• 2: Parameters
• 3: MQTT Bridge

1 - Connections

Connections are the main building blocks of a BTConnect system. There are two groups of connections:

1. Device connections: These represent a protocol connection with an external device, e.g. a DHD core connected via ECP, a MIDI input or output device, a Livewire device etc.
2. Facility connections: These are virtual connections that provide functionality to BTConnect, for example e-mail notifications, the HTTP REST API or an XML output facility.

BTConnect can handle as many concurrent connections as required, only limited by CPU, RAM and license.

Each connection has a unique ID (e.g. dhd-studio1) that is used when addressing the connection and its parameters (see below).

Internally, connections are designed as “micro-services” - they run in their own separate environment (thread), and they communicate with the other connections over a message bus.

2 - Parameters

Each connection may expose one or more parameters, which represent the information and control parts provided by the respective protocol.

Parameter IDs

Just like connections, parameters have a unique ID, with the forward slash (/) used to create a hierarchical and human-readable structure, the parameter tree.

Generally, only small letters and numbers should be used for the parts of the ID, some protocols make exceptions though (e.g. the Ember+ consumer which uses the exact node name, even if it contains capital letters, spaces etc.)

Here are some real-life examples of parameters:

• logic/87 - the logic with the ID 87 (used by DHD ECP)
• channel/1/level - the fader level of channel 1 (used by DHD ECP)
• input/3/silence/left - silence detection status for the left channel of input 3 (used by Livewire LWCP)

When referenced outside the scope of a connection, parameter IDs are prefixed with the connection ID, e.g. dhd-studio1/logic/87.

Value Types

Each parameter carries exactly one value, which is unknown by the time the software starts. The value can be one of the following four types:

• boolean (true or false)
• integer number
• floating-point number
• string
• trigger

Triggers are only used in some write-only parameters, in order to trigger an action, e.g. calling a predefined number on a codec.

Whenever necessary, BTConnect will automatically convert between the value types, on a best-effort basis. In particular:

• float to integer: fractional part is truncated
• string to float: use a point (.) as the decimal separator
• string to boolean: the strings true (case-insentitive) or 1 are regarded as true, everything else as false
• integer or float to boolean: any non-zero positive value is true, zero is false
• boolean to integer or float: true becomes 1, false becomes 0
• anything to trigger: any value will activate the trigger

Automatic type conversion happens frequently in the Protocol Converter and in the MQTT Bridge (as MQTT only works with strings).

Reading and Writing

Parameters can be read-only, write-only or read/write. We use the term “input parameter” and “output parameter” when referring to parameters that is read from, or written to, respectively.

3 - MQTT Bridge

The Message Queuing Telemetry Transport (MQTT) protocol was originally developed by IBM and has today become the de-facto standard for Internet of Things (IoT) communication. There is a large ecosystem of software and infrastructure that supports MQTT, including cloud-hosted IoT infrastructure by from Google Cloud, Microsoft Azure and Amazon AWS.

MQTT follows a Publish-Subscribe pattern; clients (devices) publish information on topics, and other clients can subscribe to these topics in order to receive updates. Likewise, each client can also subscribe to a set of topic that other clients publish (write) to, thus receiving commands from the other clients.

Communication is conducted through a central server, called the broker. There are several options available for MQTT brokers, included hosted servers, but also self-hosted free options like Mosquitto.

BTConnect supports the most frequently used MQTT protocol version 3.1. Each device connection has a built-in MQTT Bridge that publishes all input parameter changes to the MQTT broker, and receives output parameter values through a set of subscribed topics.

The concept of the parameter tree and the naming of its nodes was carefully chosen so that it naturally matches the guidelines for MQTT topics.

Note that using the MQTT Bridge is fully optional. It can be turned on or off individually for each connection. Internal communication between the connections of a single BTConnect instance uses an internal message bus and does not rely on the MQTT Bridge. The best practive is to enable MQTT Bridge only for those connections which you are going to integrate with the “outside IoT world”.

Note: In addition to the built-in MQTT Bridge for each connection type, there is also the “MQTT Client” connection type, which offers another way to connect to a (possibly different) MQTT broker. See the chapter on connection types for more information.

Receiving Parameter Updates

All (input) parameter updates are published to the topic <global prefix>/<connection prefix>/val/<parameter ID>, where the global prefix is an optional string set in the global configuration, and the connection prefix defaults to the connection ID (but can be adjusted in the connection settings where required).

For example, consider our example from above, the Logic 87 from our DHD core of Studio 1, with the following configuration settings:

• Global prefix = btconnect
• Connection prefix = connection ID = dhd-studio1
• Parameter ID = logic/87

Then the changes of the logic will be published to the MQTT topic btconnect/dhd-studio1/val/logic/87.

Sending Parameter Updates

You can also send updates to writable (output) parameters via MQTT by publishing to the respective MQTT topic. The topic name is the same as the one for reading, with val replaced by set. So in the above example, you would publish to btconnect/dhd-studio1/set/logic/87 in order to set the Logic 87 of the DHD core of Studio 1.