Examples
This page contains a list of examples to help you get started using the Lumiverse API. All examples are given in C++, but Python bindings for Lumiverse are also available (Python examples coming soon).
Example 1: Lumiverse Basics
Details
This program shows the basic functions of any Lumiverse program: creating a rig, creating a device, and connecting that device to a network (a process called "patching").
The code on line 12 creates a Device. Devices are required to have a unique ID, channel number (not required to be unique), and device type. Device objects have no default parameters or metadata vaules. You must provide that data yourself. The code on line 15 does just that by adding numeric data to the intensity field. Here we told the framework to set intensity to 0, with a default value of 0, a minimum of 0, and a maximum of 100. Note that if you are initializing the field, you must create a new LumiverseType object so the framework knows how to handle it in the future. Metadata fields are simply string properties of a device. You can put whatever data you want in those fields. See the full documentation for further details. We then add the device to the rig on line 21.
Getting devices connected to the network is the next step. Each Rig can have many different kinds of patches, but the most commonly used one is a DMXPatch. DMXPatches assign each DMX universe (an array of 512 bytes) to a user specified Interface. In this example, we choose a KiNet interface for universe 1. We create that interface and initialize it on line 28.
The DMXPatch then needs to know how to translate myFirstDevice to the DMX network. We do this by first defining a "device map" on lines 35-36. This map consists of a parameter name and a struct describing the DMX offset and conversion type. The DMX offset tells Lumiverse where to write the converted value to. For example, if a device is patched at address 45 and the Pan parameter has an offset of 4, then the pan is written at address 45+4. In our case, the intensity is the only parameter the device has and thus needs no offset from the start address. The conversion type here takes the LumiverseFloat and converts it to a value between 0 and 255. Lumiverse implements a fixed number of conversion types, which can be found in the docs (see DMXDevicePatch). We add this device map to the patch identifying it with an id of our choice.
Finally, we tell the patch where to write the DMX values for our device to. On line 41 we patch myFirstDevice to address 0, universe 1, using the device map we just created.
Once the devices have been loaded and patched, the rig is ready for use. Before doing anything with the rig, we always first initalize the rig (if this is the first time in the program the rig has been used) to allow the patches to connect to their respective interfaces. We then call run() to get the update loop started. This loop will constantly send the state of the rig to the patches according to a user-specified refresh rate (typically 40 as per the DMX standard). We can now use the devices in the rig. On line 51 we set the intensity of myFirstDevice to 100%. We then retrive that value from the rig and print it.
Lumiverse is also able to save the Rig configuration for easy access at a later time. The save function will write a JSON file to the disk containing the data stored in the Rig. You can then load the file in future programs by calling
Rig rig("/path/to/myRigFile.rig.json")rig.save("/path/to/myRigFile.rig.json", true)Example 2: Device Selection
Download Source (query.cpp) | Download Rig File
Details
Lumiverse supports a number of different ways to select and filter devices in the Rig. The above example demonstrates some of the basic syntax used for selecting devices. A more detailed description of the selection syntax can be found here.
Some things of note in the above example. Any expression in [] after the initial query is treated as filtering out that first query. So for example in line 33, Lumiverse will first select all lights with metadata field "Area" equal to "2" and then from those devices, return the devices with metadata field "gel" equal to "L201". Most queries in Lumiverse can be reduced to a single select and filter operation.