ssilverman / rdm-schema Goto Github PK

What is the logic behind the capitalisation of name values? It seems to be a mix between snake case and screaming snake case but I'm not sure why one value is one way and another is the other style.

Set request contains "units" and "prefixPower". It shouldn't

Referencing #14 I'm pulling out the "Informs/Informed By" extension into its own issue for discussion.
There are currently two areas i can think of where it is useful to know if and how one parameter is informing another. In this issue we are looking at how the UI in an application is informed by another. For example, When an application wants to show the available languages a device can be set to it would use this parameter to show LANGUAGE_CAPABILITIES, but when actually setting it uses LANGUAGE.

An example:

"name": "LANGUAGE_CAPABILITIES",
"pid": 160,
...
"extensions": {
  "ui-informing": {
    "name" : "LANGUAGE",
    "pid" : 176
  }
}

"name" : "LANGUAGE",
"pid" : 176,
...
"extensions": {
  "ui-informed": {
    "name" : "LANGUAGE_CAPABILITIES",
    "pid" : 160
  }
}

Both extensions if null in the json would default to "This parameter is not informed by another, or does not inform another."

The get response of ENDPOINT_TO_UNIVERSE uses a reference to the first field of the get request:

  "get_response": [
    { "$ref": "#/get_request/0" },
   ...

The get response of DMX_PERSONALITY_DESCRIPTION repeats the field:

  "get_response": [
    { "name": "personality", "type": "uint8" },
   ...

Whilst both are valid. What is the preferred approach?

Versioning. Perhaps we change the schema's $id each time there's an update? We could include the version in the URI. Some possibilities:
https://estalink.us/schemas/v1.0.1/rdm-schema.json
https://estalink.us/schemas/rdm-schema-v1.0.1.json

I'd favour the former example, you can then also have a symlink https://estalink.us/schemas/latest/rdm-schema.json which always points to the most recent version and the filename itself is always the same when downloaded, which is probably easier for software to manage (assuming the version is represented as a property within the JSON file too. I see it's currently in the id, it might be nice to have it duplicated as a clear semver field too, which doesn't require any fiddly parsing of the URL, although duplicating a value isn't great either.

So currently, none of the examples will validate. Here's why (excerpt from the new "Notes on the examples" section in the README):

Manufacturer ID zero

All the example messages use a manufacturer ID of zero, even though that will
not validate against the schema. There was some discussion on this and these are
the reasons:

1. It is stated in several places that manufacturer IDs must be >= 1. See:
   1. ANSI E1.20
   2. Control Protocols Working Group - Manufacturer IDs
2. It will ensure that even if someone uses the example messages as a base for
   their own messages, say using cut & paste, they will still need to choose
   their own manufacturer ID.
3. Zero is ESTA's manufacturer ID.

Love your input if you would like to share here. It would be relayed to the group next time the group meets.

Originally posted by @ssilverman in #9 (comment)

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"
  ]
}

In ANSI E1.37-2 – 2015 DNS_IPV4_NAME_SERVER is used as name for getting a name server. In the json "name server" is written as one word, DNS_IPV4_NAMESERVER. It would be logical to follow the naming in the spec?

Fields duplicated across parameters should use the same "name" value.
For example DEVICE_INFO contains the personality index and dmx start address, but uses different names for those fields rather than what is used in DMX_PERSONALITY and DMX_START_ADDRESS.

Schemas at the moment are inferred to be the same/valid for all devices by the absence of a device_model_id, software_version_id and root boolean value.

If that is the case, these should be made optional in the schema and stated in the standard as to their meaning when absent.

Shouldn't restrictToLabeled = true be added for the IDENTIFY_DEVICE PID?

As also interpreted by the ola tests: https://github.com/OpenLightingProject/ola/blob/master/tools/rdm/TestDefinitions.py#L4050 , any other value than 0 or 1 is not accepted.

Same goes for PAN_INVERT, TILT_INVERT, PAN_TILT_SWAP,

Although not listed explicitly mentioned in the spec, it seems for all these restrictToLabeled apply?

Hi,

In the json description of OUTPUT_RESPONSE_TIME_DESCRIPTION and MODULATION_FREQUENCY_DESCRIPTION there is a GET parameter: response_time_setting_count

Is this a (copy/paste) error, as ANSI E1.37-1 – 2012 (R2017) does not mention an additional GET parameter, aside from the requested setting's number?

Referencing #14 and @peternewman comment I'm pulling out the general concept of extensions, allowing a schema to contain meta data alongside a parameters data definition.

A few topics up for discussion.

• The format of extensions within the .json file.
• Are there some extensions that are required and considered set to default values if missing?
• Manufacturer specific extensions.

There is a plausible scenario where a manufacturer may want to write a manufacturer specific version of an E1.20 parameter, for example:

{
  "scope": { 
    "esta_manufacturer_id": 12345,
    "device_model_id": 1337,
    "software_version_id": 12345678,
    "root": true
  }
  "name": "DMX_PERSONALITY",
  "pid": 224,
  "version": 1,
  "get_request_subdevice_range": [ "root", "subdevices" ],
  "get_request": [],
  "get_response": [
    {
      "name": "personality",
      "type": "uint8",
      "ranges": [
        { "minimum": 1, "maximum": 3 }
      ],
      "labels": [
        { "name": "1_ch", "value": 1 },
        { "name": "direct", "value": 2 },
        { "name": "direct_plus_strobe", "value": 3 }
      ]
    },
    { "name": "personality_count", "type": "uint8" }
  ],
  "set_request_subdevice_range": [ "root", "subdevices", "broadcast" ],
  "set_request": [
    { "$ref": "#/get_response/0" }
  ],
  "set_response": []
}

I've used the scope property referred to in #13, but do we think this should be a thing?

https://github.com/ssilverman/rdm-schema/blob/master/examples/e1.20/DISPLAY_LEVEL.json

The spec states:
To turn the display off, Display Level shall be set to 0. To turn the display on full, Display Level shall be set to 0xFF. Any value in between represents a relative intensity setting. If the device does not support relative intensity settings, any non-zero value shall be interpreted as on.

So, it should not be (by default) restricted to the current: ?
{ name: "Off", value: 0 }, { name: "Full", value: 255 },