Provide Context

[sammysmallman]

Schemas currently provide a good definition of the payload to and from a responder but little context about a parameter. In their current state a controller can only assume certain characteristics of a parameter when provided a schema or if forced not to assume, ultimately ignore the parameter altogether as it has no clue as to what to do with it.

I have found through developing a RDM Controller using the schemas as a generator for both the cached device parameter data (the responses from get requests) and the get requests themselves that there are a number of characteristics I have needed to attach to a parameter definition alongside the schema to allow the RDM controller to be both efficient with its generated get requests and automated in its process to gather parameter data.

---

Shareable

It is beneficial for a controller to know when a parameters get response payload can be shared across multiple devices. The scenario is that a controller may discover multiple devices with the same esta_manufacturer_id, device_model_id, software_version_id and whether it is the root device and if so filter the get requests it would make to each of those devices according to the current state of cached parameter values it has. For example, SOFTWARE_VERSION_LABEL is a shareable parameter, once you have the response from one device, any other devices with same esta_manufacturer_id, device_model_id, software_version_id and whether it is the root device can just use that cached value, the controller does not need to send a get request for that parameter to each of those devices.

Array

I call these type of parameters “array” parameters mainly because the responses are cached in a JSON array, but ultimately they are parameters that provide a collection of values, typicaly to be used in conjunction with another parameter. For example DMX_PERSONALITY_DESCRIPTION takes a uint8 personality index and returns the description for the personality at the given index. The idea being that a controller finds out the number of personalities from DEVICE_INFO and then generates the required get requests for each personality. To automate the process of generating the get requests after understanding a device supports this kind of parameter I have needed to first indicate that this is an “array” parameter but also provide another json schema to tell the controller what to do with it. Here is an example:

{
  "name": "DMX_PERSONALITY_DESCRIPTION",
  "pid": 225,
  "get_informed_by_parameter": {
    "name": "DEVICE_INFO",
    "pid": 96,
    "$ref": "$[7].value",
    "type": "uint8",
    "zero_based": false,
    "function": "enumerate"
  }
}

This schema indicates that for a controller to gather all possible values from DMX_PERSONALITY_DESCRIPTION, it needs to look at the responses payload from DEVICE_INFO, taking the value at index 7, and then enumerate from either 0 or 1 up to or including the value depending on zero_based, generating a get request with the index as a uint8. SENSOR_DEFINITION and SENSOR_VALUE use the value at index 10 from DEVICE_INFO, which is zero based… Without this kind of definition of what a controller should do with a parameter like this I’m uncertain how it should behave when it comes across one. The default would be to ignore it altogether, but the problem being that these types of parameters offer the visual text often presented to a user.

Action

If an application provides a representation of a device with all of its RDM parameters in an offline capacity, a boolean value indicating whether the parameter is an “action” parameter is necessary to provide a nice UX. An “action” parameters set request triggers an action on the device, CAPTURE_PRESET is a good example as it has no get response, so no values to be cached by the application, and the whole purpose of it is to trigger an action on the device when its online.

UI Representable

This one is quite self explanatory. There are a number of parameters that should never be shown to a “typical” user using an RDM controller. QUEUED_MESSAGES being a prime example. The idea here is that a manufacturer should be able to specify that they have a parameter that typically is helpful in gathering information for other functionality, but if the controller is showing a device with all of its supported parameters, this shouldn’t be shown visually.

UI Informs and Informed By

This is another front end thing, but there are certain parameters in the standard that inform the UI of another parameter. LANGUAGE_CAPABILITIES is a good example of this. When an application wants to show the available languages a device can be set to it would use this parameter to show them, but when actually doing the setting it uses LANGUAGE. It would be helpful if the schema could tell me this.

---

Sorry for the wall of text, there may be more but thats enough for now. The point I would like to get across though is that: - With the schema not specifying these points, a controller has to make an assumption about a parameter. Some of those assumptions are easy to make and whilst not as performant, functionally the controller would still work by assuming the worst, shareable for instance would default to false and the controller would send a good few messages more, but thats it. action would default to false and the application would show the parameter even when the device is offline, no big deal. The lack of array though can render a parameter useless.

As an example of perhaps how we could work this into the schema:

{
  "name": "DMX_PERSONALITY_DESCRIPTION",
  "pid": 225,
  "version": 1,
  "get_request_subdevice_range": [
    "root",
    "subdevices"
  ],
  "get_request": [
    {
      "name": "personality",
      "type": "uint8",
      "ranges": [
        {
          "minimum": 1,
          "maximum": 255
        }
      ]
    }
  ],
  "get_response": [
    {
      "name": "personality",
      "type": "uint8"
    },
    {
      "name": "dmx_slots_required",
      "type": "uint16",
      "ranges": [
        {
          "minimum": 0,
          "maximum": 512
        }
      ]
    },
    {
      "name": "description",
      "type": "string",
      "maxLength": 32,
      "restrictToASCII": true
    }
  ],
  "extensions": {
    "esta_backend": {
      "shareable": true,
      "array": {
        "name": "DMX_PERSONALITY_DESCRIPTION",
        "pid": 225,
        "get_informed_by_parameter": {
          "name": "DEVICE_INFO",
          "pid": 96,
          "$ref": "$[7].value",
          "type": "uint8",
          "zero_based": false,
          "function": "enumerate"
        }
      },
      "esta_frontend": {
        "action": false,
        "uiRepresentable": true,
        "uiInforms": {
          "name": "DMX_PERSONALITY",
          "pid": 224
        }
      }
    }
  },
  "extensions_used": [
    "esta_backend",
    "esta_frontend"
  ],
  "extensions_required": [
    "esta_backend",
    "esta_frontend"
  ]
}

[peternewman]

Can I start with a meta comment @sammysmallman . From past similar discussions in other repos, I'd say these are numerous separate issues, and so some threading of discussion would be very useful, either with GitHub Discussions (not currently enabled on this repo) and a new top level comment in one thread for each suggestion, or otherwise closing this issue and splitting it into multiple new issues.

I'd suggest the latter, with a meta issue covering the general concept of extensions and probably generally how they'd fit into the schema. Then a separate issue for each extensions, as some like action say may be pretty trivial (the most complex I can think of is the interlocked INTERFACE_APPLY_CONFIGURATION) whereas others like Informs/Informed By could be more involved and hence want more discussion with something like DEFAULT_SLOT_VALUE which is chained of SLOT_INFO and the personality PIDs. The meta issue or yet another issue could also cover something you appear to have at least considered with manufacturer specific extensions to the standard too...