Introduce a parameter schema

[AtriusX]

Currently, the parameters provided by the app are all sent over as top-level snake_case variables. While this works, it poses some issues in terms of clarity and usability at scale. When configuring animation transitions in unity, it will leave all current variables in the root scope of the conditions list. This will additionally become an issue with retreiving scoped parameter endpoints if OSCQuery is ever implemented by any apps which want to remain compatible with the standard parameter list.

For these reasons I believe it would be beneficial to establish a proper naming schema for brainflow OSC parameters to ensure clarity and ease-of-use, as well as provide a standard format that can be implemented and extended by developers of other brain tracking apps.

Here is a baseline schema layout that I put together:

Brainflow:
  Sensors:
    Focus:
      - Left [float]
      - Right [float]
      - Average [float]
    Relax:
      - Left [float]
      - Right [float]
      - Average [float]
    Heart:
      - BeatsPerMinute [int]
      - BeatsPerSecond [float]
    Oxygen:
      - OxygenPercent [float]
      - RespBreathsPerMinute [int]
  Bands:
    Power:
      Left:
        - Alpha [float]
        - Beta [float]
        - Theta [float]
        - Delta [float]
        - Gamma [float]
        ...
      Right:
        - Alpha [float]
        - Beta [float]
        - Theta [float]
        - Delta [float]
        - Gamma [float]
        ...
      Overall:
        - Alpha [float]
        - Beta [float]
        - Theta [float]
        - Delta [float]
        - Gamma [float]
        ...
  Device:
    - ActiveBands [int]
    - BatteryPercent [float]
    - Connected [bool]
    - HeadsetId [int]
    - TimeSinceLastSample [float]
  AddOn:
    [AppName]:
    - HueShift [float]

This would map out to the following new parameters:

Old Parameter	New Parameter
osc_focus_left	Brainflow/Sensors/Focus/Left
osc_focus_right	Brainflow/Sensors/Focus/Right
osc_focus_avg	Brainflow/Sensors/Focus/Average
osc_relax_left	Brainflow/Sensors/Relax/Left
osc_relax_right	Brainflow/Sensors/Relax/Right
osc_relax_avg	Brainflow/Sensors/Relax/Average
osc_heart_bpm	Brainflow/Sensors/Heart/BeatsPerMinute
osc_heart_bps	Brainflow/Sensors/Heart/BeatsPerSecond
osc_oxygen_percent	Brainflow/Sensors/Oxygen/OxygenPercent
osc_respiration_bpm	Brainflow/Sensors/Oxygen/RespBreathsPerMinute
osc_band_power_left_alpha	Brainflow/Bands/Power/Left/Alpha
osc_band_power_left_beta	Brainflow/Bands/Power/Left/Beta
osc_band_power_left_theta	Brainflow/Bands/Power/Left/Theta
osc_band_power_left_delta	Brainflow/Bands/Power/Left/Delta
osc_band_power_left_gamma	Brainflow/Bands/Power/Left/Gamma
osc_band_power_right_alpha	Brainflow/Bands/Power/Right/Alpha
osc_band_power_right_beta	Brainflow/Bands/Power/Right/Beta
osc_band_power_right_theta	Brainflow/Bands/Power/Right/Theta
osc_band_power_right_delta	Brainflow/Bands/Power/Right/Delta
osc_band_power_right_gamma	Brainflow/Bands/Power/Right/Gamma
osc_band_power_overall_alpha	Brainflow/Bands/Power/Overall/Alpha
osc_band_power_overall_beta	Brainflow/Bands/Power/Overall/Beta
osc_band_power_overall_theta	Brainflow/Bands/Power/Overall/Theta
osc_band_power_overall_delta	Brainflow/Bands/Power/Overall/Delta
osc_band_power_overall_gamma	Brainflow/Bands/Power/Overall/Gamma
osc_battery_lvl	Brainflow/Device/BatteryPercent
osc_is_connected	Brainflow/Device/Connected
osc_time_diff	Brainflow/Device/TimeSinceLastSample
HueShift	Brainflow/Addon/BrainflowsInfoVRC/HueShift

NEW

• Brainflow/Device/HeadsetId
  • Maps the hardware ID of the connected device, according to a mapping table. Supports up to 255 unique device types.
• Brainflow/Device/ActiveeBands
  • The number of named bands the connected device supports. Example: The Muse 2 having Alpha, Beta, Theta, Delta, and Gamma, this would be 5. For other interfaces this may be greater or fewer.
• Brainflow/Addon//...
  • Added scope to allow for app-specific features or custom schemas. HueShift could be moved to this for example.

The benefits of this approach would allow us to provide scoping to both the Unity conditions list, as Unity supports using / to consolidate parameters into collections. OSCQuery also uses this to retrieve groups of parameters whenever you query for a specific group on an OSC app's TCP server.

Migration Steps

To move the existing parameters over to the new ones, a deprecation phase will likely be needed to ensure compatibility. This can be done in several steps:

1. Move parameter transport logic into a new class OSCParameter which has the primary focus of sending data over to VRChat or any other app that is listening.
2. Create an enum class OSCEndpoint which provides mappings for each supported endpoint and its backup values (these being the deprecated endpoints).
3. Pass items from this to build instances of OSCParameter which will send a given value to all endpoints in the OSCEndpoint class.
4. Decide on an EOL support date for the backup endpoints, and announce it to users so they have time to migrate their prefabs over.
5. After deprecation cycle, remove the backup endpoints from the OSCEndpoint class, formally drop support at this point.