====== Ember+ Remote Control ======

[[https://github.com/Lawo/ember-plus/wiki|Ember+]] is a lightweight control protocol developed by Lawo and L-S-B Broadcast Technologies. It was published an open standard, and various companies have implemented Ember+ in their products since.

In Ember+, a device (or software) can act as a "provider" or as a "consumer". The provider, e.g. a mixing console, publishes a tree of "parameters" which reflect the current status of the system (e.g. fader on/off, volume levels, etc.). The "consumer" acts as a client, subscribes to parameter changes, and can also send parameter updates in order to make changes to the provider where possible.

mAirList implements an Ember+ consumer which can be used as a regular remote control inside mAirList.

===== Supported Hardware =====

mAirList can connect to any kind of Ember+ provider. However the following limitations apply (as of mAirList 5.3):

  * As mAirList scans the entire parameter tree during startup, the tree should not be too large, for optimal performance.
  * For the same reason, the parameter tree must not be recursive (or infinite).

A list of manufacturers who have implemented Ember+ in their products can be found [[https://github.com/Lawo/ember-plus/wiki|in the ember-plus Wiki]]. Products include [[https://www.lawo.com/de/produkte/virtual-radio/r3lay-vrx-jade-studio.html|Lawo R3LAY VRX]] (formerly JADE Studio), and also DHD Series 52 with firmware 8.x.x.x (as an alternative or addition to the native DHD control protocol).

===== System Requirements =====

The Ember+ remote is based on ember_slim.dll which requires Microsoft Visual C++ Redistributable 2013 **x86** to be installed on your system: http://www.microsoft.com/en-us/download/details.aspx?id=40784

===== Configuration =====

Open the standalone configuration app or the Control Panel, go to the //Remote Control// page, and add a new //Ember+ Consumer// remote.

==== Connection setup and monitor =====

To establish a connection to an Ember+ provider, first enter the IP address or hostname, and the TCP port (usually 9000).

When you are adding a new Ember+ remote, or when using the standalone config app, check the //Monitor// option to establish a connection to the provider and enable the monitor and parameter tree (see below). When reconfiguring an existing remote from the Control Panel while mAirList is running, the monitor will always be enabled. 

{{ :config:remotecontrol:pasted:20160906-085033.png?400 }}

In the Monitor list, mAirList displays all received parameter changes from the provider, and you can double-click a row in order to assign a new remote control command to a particular parameter.

==== Commands ====

On the //Commands// tab, you assign [[reference:remote_control_commands|remote control commands]] to Ember+ parameter changes.

{{ :config:remotecontrol:pasted:20160906-090831.png?400 }}

Parameter names are specified in a path-like manner, using the ''/'' sign as a separator. The easiest way to assign a command to a parameter is to double-click a parameter in the monitor or parameter tree view, but you may also add one manually.

For numeric parameters, various conditions (equal, greater than, greater or equal, ...) can be used to match the received value.

In the //Value// field, just enter the parameter value that should trigger the command, which you must select from the dropdown list or type manually.

Please note that boolean parameters use the values ''true'' and ''false'' (in lower case letters).
==== Parameter tree ====

When the monitor function is enabled on the //Connection// tab, mAirList will propagate the parameter tree which is display on the last tab of the configuration dialog:

{{ :config:remotecontrol:pasted:20160906-090918.png?400 }}

Parameter updates received from the provider will be displayed in real time, and you can also double-click any parameter in order to assign a remote control command to it (see above).

===== Scripting =====

The Ember+ remote control provides a script extension that can be used to send parameter updates to the Ember+ provider from a script.

The remotes are accessed by the following function:

  function EmberPlusConsumerRemote(iIndex: integer): IEmberPlusConsumerRemote;

Remotes are 0-based, so ''EmberPlusConsumerRemote(0)'' returns the first Ember+ remote in the system, as a reference to an ''IEmberPlusConsumerRemote'' interface. That interface provides a method for parameter updates:

  procedure SetParameterValue(iIDPath: string; iValue: string);

''IDPath'' is the path to the parameter in the tree, using the ''/'' sign as the delimiter (the same notation as used in the remote control command assignments, see above).

Example:

  EmberPlusConsumerRemote(0).SetParameterValue('/Device/SomeLabel', 'foobar');

Note that the value is always given as a string, mAirList will automatically convert it to the correct type. Use '''true''' and '''false''' for boolean parameters.

Important notice: mAirList fetches the entire parameter tree from the provider. This is an asynchronous operation, and depending on the size of the tree, it can take a few seconds until the entire tree is known to mAirList. If you try to set a parameter that has not been fetched yet (e.g. in an ''OnLoad'' procedure that is executed during startup), you wil see an //Unknown parameter// error message. In this case, try to defer the call for a bit, using a ''sleep(...)'' operation.