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.

Last modified June 24, 2021