wiki.openlighting.org - User contributions [en]

RDM Responder Testing

2011-01-02T06:34:54Z

124.169.210.29:

[[OLA]] comes with a suite of tests for [[RDM]] responders which can be used to check how well an RDM device implements the E1.20 specification. [[Writing RDM Responder Tests]] explains how to add to / improve the tests.

== Setup the Test Rig ==

The following controller devices are supported:
* [[RDM-TRI]]
* [[DMXter4 RDM]] / [[MiniDMXter]]

Connect the device under test to the controller device and start ''olad''. Patch the output port on the controller device to a universe (UNIVERSE_NUMBER). Then run ''ola_rdm_discover'', you should see the responder's UID appear:

$ ola_rdm_discover -u UNIVERSE_NUMBER
00a1:00010003
7a70:ffffff00

== Running the Tests ==

The tests are written in Python and run using ''ola_rdm_test.py''. Below is the output from a typical test run:

./ola_rdm_test.py --universe 1 --pid_file ../../python/pids.config 00a1:00010003
Starting tests, universe 3, UID 00a1:00010003
SetManufacturerLabel: Passed
SetSoftwareVersionLabel: Passed
GetManufacturerLabel: Passed
GetSoftwareVersionLabelWithData: Failed
...
------------- Warnings --------------
------------ By Category ------------
Product Information: 7 / 7 100%
RDM Information: 1 / 1 100%
Core Functionality: 2 / 2 100%
Error Conditions: 10 / 16 62%
DMX512 Setup: 3 / 3 100%
-------------------------------------
29 / 30 tests run, 23 passed, 6 failed, 0 broken

== Useful Options ==

''ola_rdm_test.py'' has some options which can assist in debugging failures. For a full list of options run with -h

; -d, --debug
: Show all debugging output, including actual & expected responses.
; -l, --log
: Log the output of the tests to a file. The UID and timestamp is appended to the filename
; -t Test1,Test2 , --tests=Test1,Test2
: Only run a subset of the Tests. Only the tests listed (and their dependencies) will be run.

== Information on Tests ==

Some tests have dependencies, which are other tests that need to be completed before the test can be run. Dependencies can be used to check for supported parameters and other conditions that may affect responder behavior.

There are 4 result states for a test:

; Passed
: The responder replied with the expected result
; Failed
: The responder failed to reply, or replied with an un-expected result
; Not Run
: This test wasn't run because the responder doesn't support the required functionality
; Broken
: An internal error occurred, this indicates a programming error or an error with the test rig.

Writing RDM Responder Tests

2011-01-02T05:20:40Z

124.169.210.29: /* Guidelines */

This page describes how to author new RDM Responder tests. Read [[OLA RDM Responder Testing]] for information on running the tests and some general information about the testing framework.

== Basic Test Structure ==

The tests are defined in tools/rdm/TestDefinitions.py . Each test subclasses the ResponderTest class and provides the Test() method which is used to send the RDM request.

=== Dependencies ===

Tests can have dependencies, which enables the conditional running of tests if conditions match. Dependencies are defined in the DEPS variable

=== Categories ===

Each test belongs to a category (defined in tools/rdm/ResponderTest.py). Categories follow those in the RDM Categories/Parameter ID Defines table in the E1.20 document but there are some extra categories for specific behavior like TestCategory.ERROR_CONDITIONS and TestCategory.SUB_DEVICES . The category a test belongs to is defined in the CATEGORY variable.

=== PID ===

The PID variable defined which PID this test will exercise (tests can exercise multiple PIDs but that's more complicated). The PID variable should be set to a string that exists in the PidStore data file.

== Example 1 ==

This shows a test which checks that a GET request for PID ''DMX Start Address'' behaves correctly.

<pre>
class GetStartAddress(ResponderTest):
"""GET the DMX start address."""
CATEGORY = TestCategory.DMX_SETUP
PID = 'dmx_start_address'
DEPS = [GetDeviceInfo]

def Test(self):
result = ExpectedResult.NackResponse(self.pid.value,
RDMNack.NR_UNKNOWN_PID)
if self.Deps(GetDeviceInfo).GetField('dmx_footprint') > 0:
result = ExpectedResult.AckResponse(self.pid.value, ['dmx_address'])
self.AddExpectedResults(result)
self.SendGet(PidStore.ROOT_DEVICE, self.pid)
</pre>

Things to note:
* The GetStartAddress test depends on the GetDeviceInfo test to ensure that the device reports a dmx footprint > 0. This is because devices with a footprint of 0 are not required to implement the DMX Start Address PID.

== Advanced Functionality ==

=== Warnings ===

Warnings can be recorded when we detect behavior which while not serious enough to cause a failure should still be correctly. Warnings are printed in the summary section of the test output. To record a warning use the AddWarning() method:

<pre>
if footprint > MAX_DMX_ADDRESS:
self.AddWarning('DMX Footprint of %d, was more than 512' % footprint)
</pre>

=== Pre Conditions ===

A test may not want to run if certain conditions aren't satisfied. The PreCondition() method allows a test to prevent itself from running. For example, we only want to run the GetParamDescription test if we find manufacturer specific PIDS:

<pre>
def PreCondition(self):
params = self.Deps(GetSupportedParameters).supported_parameters
self.params = [p for p in params if p >= 0x8000 and p < 0xffe0]
return len(self.params) > 0
</pre>

=== Verification Methods ===

Sometimes it's not enough to check the presences of fields, or use simple equality matching. The VerifyResult() method is passed the full RDM response and can be used to implement complex inter-field checking.

<pre>
def VerifyResult(self, unused_status, fields):
"""Check the footprint, personalities & sub devices."""
footprint = fields['dmx_footprint'] if footprint > MAX_DMX_ADDRESS:
self.AddWarning('DMX Footprint of %d, was more than 512' % footprint)
if footprint > 0:
personality_count = fields['personality_count']
current_personality = fields['current_personality']
if personality_count == 0:
self.AddWarning('DMX Footprint non 0, but no personalities listed')
</pre>

== Mixins ==

Mixins are classes which abstract away common functionality to make it easier to author tests. Mixins are defined in tools/rdm/TestMixins.py.

<pre>
class GetDeviceLabel(TestMixins.GetLabelMixin, ResponderTest):
"""GET the device label."""
CATEGORY = TestCategory.PRODUCT_INFORMATION
PID = 'device_label'
</pre>

This test didn't need any code at all. We simply inherit from the GetLabelMixin, which provides it's own Test() method. Remember when using Mixins to inherit from ResponderTest last, otherwise the Test() method in ResponderTest will be used and the test will be marked as BROKEN.

== Guidelines ==

* Avoid the use of multiple expected responses. With good use of test dependencies, a test should know what to expect before we send the request.
* Always include a doc string. These are used in the debugging output to describe the test
* Try to keep the number of dependencies for each test to a minimum. Additional dependencies increase the chance the test won't be run because a dependency failed.
* Use the IsSupportedMixin where ever possible.

Help:Contents

2011-01-02T01:22:50Z

124.169.210.29: Replaced content with "Consult the [http://meta.wikimedia.org/wiki/Help:Editing Editing Guide] for information on using the wiki software."

Consult the [http://meta.wikimedia.org/wiki/Help:Editing Editing Guide] for information on using the wiki software.

Open Lighting Architecture

2010-12-30T02:32:44Z

124.169.210.29:

[[Image:Ola.png|right]]
Link: http://code.google.com/p/linux-lighting/ 
{{Features|free=yes|tx=yes|rx=yes|linux=yes|osx=yes|http=yes|rdm=yes}}
[[Image:Ola-download.png |right|link=http://code.google.com/p/linux-lighting/downloads/list]]
[[Image:Llad_home.png| thumb |200px|right|Universe Settings]]
[[Image:Ola-rdm.png|thumb|200px|right|RDM Devices Page]]
[[Image:OLA_patching.png|thumb|200px|right|Drag & Drop RDM Patching]]
[[Image:Ola-mobile.png|thumb|200px|right|Mobile UI]]

__NOTOC__
The Open Lighting Architecture (OLA) is an open source framework which provides applications with a mechanism to send and receive [[DMX512]] & [[RDM]] commands using hardware devices and DMX over IP protocols. It enables [[:Category:Controllers | software controllers]] to communicate with hardware either via Ethernet or over traditional DMX512 networks. The [[Open Lighting Projects List]] lists some of the places and projects where OLA is used.

OLA can also convert DMX512 data sent using DMX over IP protocols from one format to another, allowing devices from different manufacturers to interact with one another. For example a [[Strand_Lighting|Strand]] Lighting Console using ShowNet can send DMX512 to an [[Enttec]] [[DmxEtherGate MKII|EtherGate]]. When combined with a physical DMX interface such as the [[DMX USB Pro]], OLA can send and receive data from wired DMX512 networks.

==Main Features ==

* Supports a variety of DMX over IP Protocols and a dozen different USB DMX devices.
* Priority based merging of different sources.
* Built in web based configuration including:
** [[RDM]] controller
** Drag and drop RDM patching with an automatic patcher
** Custom UI for mobile devices (iPhone, Android)
* Command line tools which enable scripting of configuration and RDM commands.
* Python, C++, Objective-C++ APIs for developers to build their own applications.
* Runs on Mac OS X (ppc, i386, x86_64) & Linux ( i386, x86-64, arm).
* Source code is open and available at no cost.

A port to Windows is feasible if someone wants to add the necessary platform-dependent code.

Questions: See the [http://groups.google.com/group/open-lighting mailing list]

Bugs: Check the [http://code.google.com/p/linux-lighting/issues/list bug tracker]

Contribute: Looking to help? Visit the [[OLA Contributors]] page. The page also lists people and companies who have supported OLA. Please support them in return!

==Supported Protocols==

{| border=1 cellspacing="0"
! '''Protocol'''!! Linux !! '''Mac OS X'''
|-
|| [[:Category:ArtNet|ArtNet]] || [[Image:Green-tick.png|center]] [[Image:Rdm.gif|center]] || [[Image:Green-tick.png|center]]
[[Image:Rdm.gif|center]]
|-
|| [[E1.31]] / [[ACN]] || [[Image:Green-tick.png|center]] || [[Image:Green-tick.png|center]]
|-
|| [[:Category:ESP Net|ESP Net]] || [[Image:Green-tick.png|center]] || [[Image:Green-tick.png|center]]
|-
|| [[:Category:Pathport|Pathport]] || [[Image:Green-tick.png|center]] || [[Image:Green-tick.png|center]]
|-
|| [[:Category:Sandnet|Sandnet]] || [[Image:Green-tick.png|center]] || [[Image:Green-tick.png|center]]
|-
|| [[:Category:ShowNet|ShowNet]] || [[Image:Green-tick.png|center]] || [[Image:Green-tick.png|center]]
|}

==Supported Devices==

{| border=1 cellspacing="0"
! '''Device'''!! Linux !! '''Mac OS X'''
|-
|| [[Anyma uDMX]] || [[Image:Trans.gif|center]] || [[Image:Trans.gif|center]]
|-
|| [[Arduino RGB Mixer]] || [[Image:Green-tick.png|center]] || [[Image:Green-tick.png|center]]
|-
|| [[DMX 4 Linux]] || [[Image:Trans.gif|center]] ||
|-
|| [[DMX USB Pro]] || [[Image:Trans.gif|center]] [[Image:Recv.gif|center]] || [[Image:Trans.gif|center]] [[Image:Recv.gif|center]]
|-
|| [[DMX-TRI]] || [[Image:Trans.gif|center]] || [[Image:Trans.gif|center]]
|-
|| [[DMXking USB DMX512-A]] || [[Image:Trans.gif|center]] [[Image:Recv.gif|center]] || [[Image:Trans.gif|center]] [[Image:Recv.gif|center]]
|-
|| [[DMXter4 RDM]] / [[MiniDMXter]] || [[Image:Rdm.gif|center]] || [[Image:Rdm.gif|center]]
|-
|| [[Open DMX USB]] || [[Image:Trans.gif|center]] ||
|-
|| [[Packetheads USB_DMX Dongle]] || [[Image:Green-tick.png|center]] || [[Image:Green-tick.png|center]]
|-
|| [[RDM-TRI]] || [[Image:Trans.gif|center]] [[Image:Rdm.gif|center]] || [[Image:Trans.gif|center]] [[Image:Rdm.gif|center]]
|-
|| [[StageProfi]] || [[Image:Trans.gif|center]] || [[Image:Trans.gif|center]] (Ethernet version only)
|-
|| [http://machosehead.wordpress.com/2010/06/12/udmx_asp/ uDMX_asp] || [[Image:Trans.gif|center]] || [[Image:Trans.gif|center]]
|-
|| [[USBDMX2]] || [[Image:Trans.gif|center]] || [[Image:Trans.gif|center]]
|-
|| [[Velleman K8062]] || [[Image:Trans.gif|center]] || [[Image:Trans.gif|center]]
|}

==Getting Started==

Start here if you've never used OLA before and read these in order.
* [[Download OLA]]
* [[OLA on OS X]] or [[OLA on Linux]] - How to install OLA.
* [[Using OLA]] - A basic introduction
* [[OLA Command Line Tools]] - Documentation for the tools in ola-examples
* [[OLA Device Specific Configuration]]
* [[OLA Tips & Tricks]]
* [[RDM with OLA]]

Tutorials
* [[OlaOutput Max External]] - Setup OlaOutput on Mac OS X to send DMX messages from Max/MSP/Jitter
* [[OLAGuruPlug]] - Running OLA on a [http://www.globalscaletechnologies.com/c-4-guruplugs.aspx GuruPlug]
* [[OlaLED]] - control RGB LED via http
* [[OLA RDM Responder Testing]]

Advanced Topics:
* [[OLA Merging Algorithms]]
* [[OLA DiffServ support]] (QOS settings)

Developer Documentation:
* [[OLA developer info]] - about the source code and structure
* [[OLA Client API]] - the C++ API
* [[OLA Python API]] - easy DMX programming
* [[Build OLA Mac Packages]] - notes for building the .dmg images
* [[Building OLA for Windows]] - Notes on Windows support (in progress)
* [[Using OLA with Xcode]] - on a Mac, in Objective-C++
* [[Port Throttling]]
* [[OLA Performance Stats]]

Tutorials, these refer to the previous release but parts of them are still relevant.
* [[LLA Sandnet Tutorial]] - Setup Horizon using Sandnet and LLA
* [[LLA and Q Light Controller Ubuntu Tutorial]] - Setup LLA on Ubuntu/Debian-type distro with QLC
* [[LLA and Q Light Controller OSX Tutorial]] - Setup LLA on Mac OS X with QLC

[[Category:ArtNet]]
[[Category:ESP Net]]
[[Category:E1.31]]
[[Category:Sandnet]]
[[Category:ShowNet]]
[[Category:Utilities]]
[[Category:Pathport]]

OLA Contributors

2010-12-30T01:58:59Z

124.169.210.29: /* OLA Supporters */

==OLA Supporters==

Many thanks to the following people / organisations that have supported [[OLA]]:

* [http://www.anyma.ch Anyma], provided a [[Anyma_uDMX|uDMX]]
* [[Artistic Licence]], provided a [[Net-Lynx]] for Art-Net testing and a [[Rail-Tran]] to test [[RDM]] support
* [http://www.creativelighting.com.au/ Creative Lighting], provided a [[SLAMMO XC-1]] for [[RDM]] testing.
* [[Enttec]], provided a [[DMX USB Pro]]
* Florian from eventa.ag who donated a [[StageProfi]] and a [[USBDMX2]]
* Jason Kyle from [http://www.DMXking.com DMXKing.com] provided a [[DMXking USB DMX512-A]]
* [[JESE]], provided a [[RDM-TRI]] to test the RDM implementation.
* Shaun Jackman, answered questions about the [[:Category:Pathport|Pathport]] Protocol
* [http://www.waapa.ecu.edu.au West Australian Academy of Performing Arts] (WAAPA) for access to a [[Strand Lighting]] console.

==Contributors==

* Bastien Andrès, contributed to the dmx4linux plugin
* Heikki Junnila, bug fixes for the debian packaging files

==Help Wanted==

Can you help with any of the following? Please get in touch with us on the [http://groups.google.com/group/open-lighting Open Lighting Group]

* Technical Writers, the [[OLA]] documentation could do with some cleanup.
* Packagers, we need people to build binary packages for Mac, Debian/Ubuntu and RPM-based distros
* Windows programmers, are you interested in helping [[Building_OLA_for_Windows| port OLA to Windows]]?
* Java programmers, we need someone to write the Java client API [http://code.google.com/p/linux-lighting/issues/detail?id=15 ]
* Equipment donation, do you own or know of a [[:Category:USB | USB interface]] or RDM device we don't support yet? Consider lending it to us.
* Web designers, the web UI could do with a facelift.
* Monetary donations, cash helps buy more equipment to test with, you'll get your name listed and a warm fuzzy feeling inside :)