Personal tools
The Open Lighting Project has moved!

We've launched our new site at www.openlighting.org. This wiki will remain and be updated with more technical information.

RDM PID Definitions

From wiki.openlighting.org

Revision as of 08:52, 5 April 2013 by Nomis52 (talk | contribs) (Created page with "== 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 b…")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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': []},
  'get_response': {'items': []},
  'get_sub_device_range': <int>,
  'name': <string>,
  'set_request': {'items': []},
  'set_response': {'items': []},
  '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 is explained below
{get,set}_response
The structure of the GET / SET response, also explained below
{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