Colorbeam Lighting

Driver: colorbeam

Local control of Colorbeam color-tunable LED fixtures over the network. One GEM device represents one Colorbeam controller; each GEM zone represents one addressable fixture or keypad on that controller, identified by its Colorbeam integration id (also called the load id). GEM sends brightness, color, and white-channel commands to a fixture by its integration id, and can simulate keypad button events.

Control uses Colorbeam's plain-text TCP protocol — dash-delimited command frames such as load_id-01-50-FF8800-00-2, each terminated with a carriage-return/line-feed. The controller listens on TCP port 3333 and requires no login.

One controller, many fixtures

The device is the Colorbeam controller. You do not add a device per light — you add one device for the controller, then a zone per fixture (or keypad), addressed by that fixture's integration id. All of a controller's fixtures share the one TCP connection.

Prerequisites

• Colorbeam controller on the same LAN as the GEM server, reachable at a static IP or DHCP reservation.
• Each fixture and keypad already programmed with an integration id (load id) in the Colorbeam system. You will enter these ids as zone addresses, so have the load list from the Colorbeam commissioning to hand.
• TCP 3333 reachable outbound from the GEM host to the controller (or whatever port the controller is configured for).

Setup

1. System → Devices → Add Device. Choose the Colorbeam Lighting driver.
2. Set the Controller IP to the controller's LAN address. Leave TCP Port at 3333 unless the controller is configured differently. Save and enable — the device comes up Connected once the TCP session is open.
3. For each fixture (and each keypad), create a zone under Zones: bind it (the Device field) to this Colorbeam device, set its Subsystem to Lights, and set its Address to the fixture's Colorbeam integration id (load id).

Subsystem pre-selection

This driver hints the Lights subsystem, so if your site has the default lights subsystem the zone editor pre-selects it for you. If you renamed or removed that subsystem, pick a lighting subsystem by hand under Subsystems.

Addressing

The zone Address is the fixture's (or keypad's) Colorbeam integration id — the same load id assigned in the Colorbeam programming. That value is what GEM substitutes for [integration_id] in every command frame.

When you build a command against a Colorbeam zone (in a macro, automation, trigger, or command button), the integration id fills in from the zone's Address automatically, so setting the Address correctly per fixture is what makes the commands target the right light. Enter the id exactly as it is assigned on the controller.

How fixtures are controlled

Colorbeam does not ship a dedicated on-screen dimmer/color widget that talks to the controller directly. You drive fixtures by invoking the driver's commands — from a macro, an automation, a trigger, or a command button — with the fixture's integration id (supplied from the zone Address) plus the level, color, white, and fade values you want:

• To set brightness (and optionally the white channel) without changing the color, use the level command.
• To set brightness and color together, use the level_color command with a hex_color argument.
• To simulate a keypad button (for example, to trigger a scene wired to a Colorbeam keypad), use the button_press command against the keypad's integration id.

Attributes

Device

Attribute	Required	Default	Description
ip	yes	—	LAN IP of the Colorbeam controller (the Controller IP field).
port	no	3333	TCP port the controller listens on (the TCP Port field).

Zone

Attribute	Required	Description
address	yes	The fixture's or keypad's Colorbeam integration id (load id). Passed as [integration_id] in every command.

No other per-zone attributes are required — a Colorbeam zone is just a name plus the integration id it addresses.

Commands

Send these from a macro, a command button, or the Commands page. [integration_id] is filled from the zone Address; you supply the remaining arguments.

Command	Arguments	Wire frame	What it does
level	level, white_level, fade_rate	load_id-<id>-<level>-XXXXXX-<white>-<fade>	Sets brightness and (optionally) the white channel. The color field is fixed to XXXXXX, so the fixture's current color is left unchanged.
level_color	level, hex_color, white_level, fade_rate	load_id-<id>-<level>-<hex>-<white>-<fade>	Sets brightness and color, plus optional white channel.
button_press	button_number, action	<id> <button_number> <action>	Simulates a keypad button event on the addressed keypad.
subscribe	load_id	SUB-<load_id>	Asks the controller to push updates for a load.

Argument reference

Argument	Values	Notes
level	0–100	Fixture brightness. 0 is off, 100 is full.
hex_color	6-digit RGB hex, e.g. FF8800	level_color only. Enter the hex without a leading #.
white_level	white-channel level	For tunable / RGBW fixtures with a dedicated white channel. Leave at 0 for fixtures without one.
fade_rate	transition time	How quickly the fixture ramps to the new level/color.
button_number	keypad button number	Which button on the addressed keypad.
action	press, release, hold, double_tap	Sent on the wire as 3 / 4 / 5 / 6 respectively.

Keypad button values

The action argument accepts a menu of press, release, hold, and double_tap; GEM translates your choice to the numeric code Colorbeam expects (3, 4, 5, 6). You do not enter the number yourself.

Known quirks

• Single-digit numeric values are zero-padded to two digits before they are sent (for example a level of 5 goes out as 05). The driver does this automatically — you can enter values normally.
• level never changes color. Its color field is fixed to XXXXXX (leave-as-is). If you need to change the hue, use level_color instead.
• State is not read back. The driver can send a subscribe request, but it does not translate the controller's updates into GEM zone state. GEM therefore reflects the last value it commanded, not live feedback from the hardware — a change made at a physical keypad or another controller will not appear in GEM until GEM next commands the fixture.
• Plain TCP, no authentication. Anyone on the network segment can reach the controller on its control port; keep it on a trusted VLAN.

Troubleshooting

Symptom	Check
Device won't connect	Confirm the Controller IP is correct and the controller is reachable on TCP 3333 (or the port you set). The controller must be powered and on the same reachable network as GEM.
A command runs but the wrong light responds	The zone Address must be the fixture's Colorbeam integration id. Confirm each zone's Address matches the load list from the Colorbeam programming.
Color won't change	You are probably sending level, which leaves the color untouched. Use level_color with a hex_color argument.
GEM shows a stale brightness/color	Colorbeam state is not read back into GEM — the on-screen value is the last one GEM sent. Re-send the command from GEM to resynchronize.
A keypad button does nothing	Confirm you addressed the keypad's integration id (not a fixture's) and picked the correct button_number and action.

Related

• Devices
• Zones
• Subsystems
• Commands
• Macros