OLA Merging Algorithms

This page has migrated

This page has migrated to our new site, please see https://www.openlighting.org/ola/advanced-topics/ola-merging-algorithms/.

This content will not be updated and is just left here for reference and will be removed at some point in the future, see the link above for the most up-to-date version.

This document outlines the multi-source merging functionality in OLA.

Problem Definition

The old version of OLA had two merge modes, HTP & LTP. This didn't allow for priority based merging of multiple DMX sources and in particular, didn't work well with automated lights.

A separate but related problem what that some devices (such as the E1.31 device) support a priority field when sending DMX data. These fields should be customizable.

With the new merging features, a user can configure two input ports to be bound to the same universe, and set the priorities of the ports such that data on one is preferred over another. This can be used to implement backup controllers.

The protocols known to support priorities are:

• E1.31
• ETCNet2 (no OLA plugin)

Proposal

From the E1.31 standard, we define a source priority which is an integer in the range 0 to 200 with 0 the lowest priority and 200 the highest. The default priority is 100.

Each universe will have an active priority which is the priority that data is being handled for. Data received with a lower priority will be ignored, while data received with a higher priority will raise the universe's active priority to match that of the new data.

Input ports

Input ports will be separated into two types, those that support priorities and those that don't.

Ports that support priorities will offer two modes, inherit and override. Inherit mode will use the priority provided by the device/protocol. Override mode will allow the user to set a priority.

Ports that don't support priorities will allow the user to specify the priority, defaulting to 100.

Output ports

Output ports that support priorities will again provide inherit and override modes. Inherit mode will use the universe's active priority, ports operating in override mode will allow the user to specify a priority.

Output ports that don't support priorities won't change.

Source Clients

Source clients will be able to set a source priority when sending DMX data, this will default to 100.

Sink Clients

No changes required. We may provide the universe's active priority in the data packet if required.

Resolution of Equal Priority Data

Universes will offer a choice of HTP and LTP merge modes for when data is received from multiple ports with the same priority.

Data Timeouts

When a data source doesn't receive data for a specified interval (known as the timeout interval) it's considered disconnected. At this point the source is removed from the list of available sources and the universe's active priority may reduce. Different ports may have different timeout intervals.

Use Cases

Consider the following

• Input port A, supports priorities, operating in inherit mode.
• Input port B, doesn't support priorities, manually set to 120
• Source client without a priority (defaults to 100)
• Output port X, doesn't support priorities
• Output port Y, supports priorities

All ports are bound to the same universe. The cases described below are sequential (the events described in Case 2 assume the events of Case 1 have already occurred)

Case 1: No Merge

No data is received from either input port and the source client sends data. The active priority is 100. Output port X sends the data, output port Y sends the data with priority 100.

Case 2: Simple Merge

Data is now also received on port B. The new active priority is 120. Output port X sends the data from port B, output port Y sends the data from port B with priority 120.

Case 3: Another Simple Merge

Continuing on from Case 2, data is received on port A with a priority of 20. The active priority is still 120 so this data is discarded. Output port X continues to sends the data from port B, output port Y continues to send the data from port B with priority 120.

Case 4: Conflict Merge

New data is received on port A with a priority of 120. With two data sources of the same priority, the merge mode setting of the universe kicks in and the data from ports A and B is HTP or LTP merged depending on the universe setting. Port B continues to send with a priority of 120.

Case 5: Priority Escalation

New data is received on Port A with a priority of 180. The new active priority is 180 and the conflict merge stops. Output port X sends the data from port A, output port Y sends the data from port A with priority 180.

Case 6: Overriding the Output Port Priority

The user changes the mode of Port Y from inherit to override and sets a value of 130. Output port X continues to send the data from port A, output port Y sends the data from port A but with a priority of 130.

Case 7: Source Removal

Port A stops receiving data and is considered disconnected. The active priority drops to 120 and both output ports use the data from port B. Port Y continues to send a priority of 130 because it's operating in override mode.

Further Information

• ETCNet2 Information
• E1.31 specification (purchase required)