Using the Color agent

The Control4 Color agent enables the creation and editing of color and tunable white lighting presets. Presets allow for quick selection of a specific color (chromaticity) or tunable white (CCT) on bulbs and lighting strips that support color and/or tunable white. Presets only contain information about the color or CCT value. Brightness is not included with the preset definition. Brightness does affect the perceived color. Brightness can be set manually using the user interface and can also be set programatically using Advanced Lighting Scenes, Brightness Presets, and custom programming.

Minimum required OS version: OS 3.3.0

Quick Configuration

The Control4 Color agent is automatically added to any project installed on or updated to OS 3.3.0. You should not attempt to delete this agent. If you do, it will be added back into the project when the controller is restarted.

The Color agent includes a selection of default presets for various color selections and tunable white selections. Users may also create their own presets using the customer application. You may add system-wide presets as well. All presets can be edited and deleted. You can also change the order which will be used to display these preset selections. Note that individual lights may not be able to display all chromacity or CCT levels. The Color agent doesn't attempt to enforce this. But, when the Control4 user interface is used to set the color/temperature for the device, it will only show the available presets. In other words, the available presets will be limited based on the device's defined capabilities.

Presets

There are three categories of presets:

Default⁠—These are the default presets provided on initial installation of the Color agent.

Dealer⁠—These are the presets created by the Control4 Installer using the Color agent.

Customer⁠—These are the presets created by the user through the Control4 application.

Add Preset

Name⁠—Name each Preset. Names must be unique.

Category ⁠—The category field is read-only. All presets created by the Installer are in the Dealer category.

Preset Type ⁠—Color presets are defined by chromaticity and stored either using xy values or hue & saturation values. Color Temperature presets are defined by a color correlated temperature (CCT) value in Kelvins.

Definition ⁠—You may use the color wheel or the entry fields to specify the desired color/temperature.

Hue and Saturation ⁠—Chromaticity is specified using hue (0-359 degrees) and saturation (1-100%).

xy Chromaticity ⁠—Chromaticity is specified using the xy scale. This gives you the broadest selection of colors.

RGB ⁠—Color may be specified as an RGB value. The RGB specification combines both chromaticity and brightness. When you provide RGB values, Control4 will convert the chromaticity to xy.

Test Light ⁠—You may select one or more lights. The selected light(s) will follow the color / temperature selections so that you can visually verify the color while you are creating or editing the preset.

Edit Preset

Preset Order

You can easily change the order of the presets by dragging a preset higher or lower on the preset list.

Import/Export Presets

Exporting the preset list allows you to save the preset definition to an xml data file. This can be very helpful for restoring the presets to a known good configuration. As with other areas of Composer Pro, the Color agent doesn't have an 'Undo' function. If you make changes, and aren't happy with them, you will save a lot of time by restoring a known good configuration. If a preset with the same name is imported, it will overwrite the preset in the project. Exporting and Importing presets can also be helpful if you want to provide a standard base set of presets in all of your customer installations.

Advanced Properties

Log Settings

Log Level⁠—This property allows to filter which message types display in the Lua Output window. Options 0 ⁠—5 correspond to Fatal through Trace levels, increasing in level of verbosity.

Log Mode⁠—Activates logging of diagnostic information. The log level is set in the above property. Options include Off, Print (to the window), Log (to the Director Log), and Print and Log (both). Default is Off.

General Information

Device ID⁠—Displays agent device ID.

Agent Version⁠—Displays current agent/driver version.

OS Version Status⁠—Displays whether current OS version fulfills min requirements for Color agent.

Actions

This section lists and defines the Actions that the agent provides and are available through ComposerPro. These Actions are primarily for advanced troubleshooting. You should not need to use them for normal configuration.

List Presets⁠—Prints all defined color presets in table format to the Lua output window.

Add Preset HS⁠—Adds color preset in the HS color format. Parameters are:

NAME ⁠—Preset name (mandatory field)

CATEGORY ⁠—Preset category differentiated by who created the preset.

HUE ⁠—Hue component of HSV/HSB/HSL color space (range [0.0, 360.0])

SATURATION ⁠—Saturation component of HSV/HSB/HSL color space (range [0.0, 100.0])

Add Preset XY⁠—Adds color preset in the xy color format. Parameters are:

NAME ⁠—Preset name (mandatory field)

CATEGORY ⁠—Preset category differentiated by who created the preset.

COLOR_X ⁠—x component of xyY color space (range [0.0, 1.0])

COLOR_Y ⁠—y component of xyY color space (range [0.0, 1.0])

Add Preset RGB⁠—Adds color preset in the RGB color format. Parameters are:

NAME ⁠—Preset name (mandatory field)

CATEGORY ⁠—Preset category differentiated by who created the preset.

RGB ⁠—RGB color information.

Add Preset CCT⁠—Adds color correlated temperature preset. Parameters are:

NAME ⁠—Preset name (mandatory field)

CATEGORY ⁠—Preset category differentiated by who created the preset.

COLOR_TEMPERATURE ⁠—Color temperature in Kelvins (range [1000.0, 20000.0])

Edit Preset Name⁠—Changes name of the preset with the given ID. Parameters are:

ID ⁠—ID of the preset that is being modified.

NAME ⁠—New preset name.