Decouple Osee protocol from companion logic

[fa1k3n]

This issue is currently to be considered living , so changes will occur

Right now there is a tight coupling between the Osee communication protocol and the companion code , e.g. all
Actions are using sendCommand with the Osee parameters , some states are saved as osee logical index instead of its human understandable actual value , e.g. pip size saved as 0 instead of 0.25 .
This makes is very static and tough to adapt to protocol changes

So a few implementation points

• define a function interface between companion logic code and communication , this should as long as possible match the logic that is in the profile XML file . This would also allow to bundle messages

• state should be saved as the human understandable value not index. Index can be used if saving references to internal arrays but not for usage in the device messaging , e.g. currenKey should be PIP in the state not a 3 . Translation is handled by the communication layer not by the companion layer

[arikorn]

Some thoughts, some of which I've elaborated on in more detail in issue #106 , which is closely related to this one.

1. Here is the diagram I posted in Handling Osee Quality definition change #106, which I think is a good starting point for approaching the problem (and also illustrates why the decoupling is important: Osee introduced a "breaking change" in the protocol that is easily avoided if we decouple as described in the original post here by @fa1k3n and by me in Handling Osee Quality definition change #106):

2. Another thing to consider is the organization of files. I think that the current organization of multiple folders should be preserved, as it helps keep the code modular, however, the state object should be made more central to each submodule. I.e., it handles the translation from protocol to internal state and back, and also it informs the action and feedback definitions as to the available options (for example ["high" "med" "low"] vs. ["high" "good" "med" "low"], depending on fw version in the diagram above). To summarize the job of the Internal State Layer is:
   a. to receive and translate the communication-protocol data (possibly referring to the device instance to resolve ambiguities)
   b. to store the current state for Presentation Layer feedback (and occasionally for complex button-actions)
   c. to provide the Presentation Layer with the list of valid choices and
   d. to translate user choices back to communication-protocol data and send it to the device
   As such, it might be beneficial to define the state as a class, which can then encapsulate these data and functions. (It still makes sense though to encapsulate the low-level communication in the device-model, which can then forward or receive the extracted data to/from the states. So perhaps there are really four layers: low-level IP "packet" data (JSON in our case), low-level extracted-data representation (and object containing id and data), internal data representation (string or number), presentation data (Companion data structures).

[arikorn]

To very briefly recap the above before going on, we need to balance two goals:

1. Have a protocol that is resilient to changes in hardware and firmware communication protocols.
2. Have code that is modular so that code changes remain localized both in terms of allowing multiple programmers to work on different parts and so code logic is kept as succinct and localized as possible (DRY).

Here's a refinement and update of the previous diagram:

The basic idea is that there are four layers of abstraction in our protocol:

1. Generic low-level communication is handled inside the "device model"
2. Generic high-level communication is provided by the device model and used by the "internal state" layer
3. Internal state is handled by the Internal State layer, which provides functions for use by the "Presentation Layer"
4. The Presentation Layer uses the functions from the Internal State layer to bridge the internal state to Bitfocus Companion's presentation API

The basic idea/concepts are that (1) each layer provides functions for the next higher layer to use (2) each layer communicates directly only with the immediately adjacent layer. (3) layers 3 & 4 map the data from the previous layer into a form that is independent of the previous layer's data (so that changes in the device protocol, for example, won't change the internal data representation, just the mapping will change.)

The second part, which isn't readily apparent from the diagram, is that the state functions maintain the current modularity (folder structure) of the code, thus satisfying the second goal.

The main violations of these principles in the current codebase are:

1. The use of device-protocol values in the internal and presentation layers, as mentioned in the OP.
2. The use of ActionIds for both Companion Action names and the device-level communication id (and by calling the device layer with these names directly from the presentation layer, skipping the intervening layer).

Both of these violations recently "came to roost" with the recording quality function since (a) Osee changed the protocol in a "value-breaking" way and (b) in order to split quality into it's two unrelated components (recording vs. streaming), one needs to define two actions, but Companion does not allow two actions to have the same name, so one of these action must have a name that is not the communication id. (see fifth TODO item in issue #107)

[fa1k3n]

I agree with your four tier protocol stack, but between layer 2 and the internal state layer there should be a function interface going from the internal state layer to layer 2. So Internal state will call a function in layer 2 , e..g setUskMaskParameters (enable, hStart, vStart, hEnd, vEnd);
Then going up the stack from layer 2 to internal state there will be a event emitter interface where layer 2 emits an event every time its state has changed. This event the internal state layer can subscribe to and make changes when events are emitted.
Doing it like that will allow for breakout of Layer 1 and Layer 2 into a separate Git repo that is only for osee communications and can be imported as a dependency into the companion module. This library can then be used by other projects too, not only by Companion.