Personal tools
The Open Lighting Project has moved!

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

Difference between revisions of "RDM PID Definitions"


Jump to: navigation, search
Line 97: Line 97:
* ipv4
* ipv4
* uid
* uid
=== Optional Fields ===
These are only defined for certain types.

Revision as of 09:12, 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 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 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 code from The definitions are found in data/ 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 site.


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

  {'id': <int>,   # the manufacturer ID, written in hex
   'name': <string>,  # the manufacturer name
   '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 
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.
The structure of the GET / SET response, same structure as the _request fields.
A value between 0 and 3 which places restrictions on the value of the SubDevice field in the RDM message.
The name of the PID, should be in CAPS like the names in E1.20
A URL pointing to where this information was obtained, set to the empty string is there isn't one
A text description of what this parameter does. This should be explain to the user how to use the parameter.
The parameter ID (PID).

The allowed values for the sub_device_ranges are:

ROOT_DEVICE, implies the subdevice field is 0x0000
ROOT_OR_ALL_SUBDEVICE, the subdevice field is 0x0000 to 0x0200 or 0xffff
ROOT_OR_SUBDEVICE, the subdevice field is 0x0000 to 0x0200
ONLY_SUBDEVICES, the sub device field is 0x0001 to 0x0200

If a {get,set}_request field isn't present, this means the parameter doesn't support the GET / SET operation. In that case the corresponding _response field should also not be present. Note that this differs from a _request field which is present, but contains no items. The latter means that the parameter data length is 0.


Items represent the data fields within each message. An item can be a group of items, this is how repeated fields are supported.

  'name': <str>,
  'type': <string>',

Valid types:

  • bool
  • uint8
  • uint16
  • uint32
  • int8
  • int16
  • int32
  • string
  • group
  • ipv4
  • uid

Optional Fields

These are only defined for certain types.

labels multiplier range min_size max_size