Difference between revisions of "RDM PID Definitions"

Revision as of 07:54, 5 April 2013

Parameter Definitions and OLA

OLA reads the structure of RDM parameter messages at runtime. This allows the users to update PID definitions without upgrading the binaries and also means we can add knowledge of new manufacturer PIDs to the RDM controller software very quickly.

The canonical PID definitions are stored on the http://rdm.openlighting.org site. The site can generate ASCII protocol buffers which are checked into the OLA codebase and distributed with the tarball. One day we may support automatic updating of the PID files.

You can see the latest pid protobufs at pids.proto and manufacturer_pids.proto. In the tarball the files are in data/rdm/ and they are usually installed into /usr/local/share/ola/pids/.

Adding New Parameters

Parameters are added to the rdm.openlighting.org site by specifying the message structure, as well as properties like the parameter name and ID in a Python file. To get started, clone the rdm.openlighting.org code from http://code.google.com/p/open-lighting/source/checkout?repo=rdm-app. The definitions are found in data/pid_data.py. Once you have edited this file push the change to a public git repo and email the open-lighting list asking for a pull request. Simon will sanity check the new parameters and push them to the rdm.openlighting.org site.

Structure

The parameter definitions file is just a Python data structure. At the top level there are two variables MANUFACTURER_PIDS and ESTA_PIDS.

MANUFACTURER_PIDS = [
  {'id': <int>,   # the manufacturer ID, written in hex
   'name': <string>,  # the manufacturer name
   'pids': [<parameter_definition>],
  },
  ...
]

ESTA_PIDS = [
  <parameter_definition>
]

Each Parameter Definition takes the form:

{
  'get_request': {'items': [<item>]},
  'get_response': {'items': [<item>]},
  'get_sub_device_range': <int>,
  'name': <string>,
  'set_request': {'items': [<item>]},
  'set_response': {'items': [<item>]},
  'set_sub_device_range': <int>,
  'link': <string>,   # the URL for more information
  'notes': <string>,
  'value': <int>,  # the PID 
}

{get,set}_request

The structure of the GET / SET request. This specifies a list of items which are the fields in the parameter message. See the section below for more details.

{get,set}_response

The structure of the GET / SET response, same structure as the _request fields.

{get,set}_sub_device_range

A value between 0 and 3 which places restrictions on the value of the SubDevice field in the RDM message.

name

The name of the PID, should be in CAPS like the names in E1.20

line

A URL pointing to where this information was obtained, set to the empty string is there isn't one

notes

A text description of what this parameter does. This should be explain to the user how to use the parameter.

value

The parameter ID (PID).

The allowed values for the sub_device_ranges are:

0

ROOT_DEVICE, implies the subdevice field is 0x0000

1

ROOT_OR_ALL_SUBDEVICE, the subdevice field is 0x0000 to 0x0200 or 0xffff

2

ROOT_OR_SUBDEVICE, the subdevice field is 0x0000 to 0x0200

3

ONLY_SUBDEVICES, the sub device field is 0x0001 to 0x0200