Basic Usage
Initialization
Initializing an OpenRGBClient
is pretty simple.
from openrgb import OpenRGBClient
cli = OpenRGBClient()
That’s it as long as you are controlling a local OpenRGB SDK, using the default port, and don’t want to change the name. If this is not the case, there are a few more options.
cli = OpenRGBClient('192.168.1.111', 8000, 'My client!')
This will connect to an OpenRGB SDK server at 192.168.1.111:8000
with
the name My client!
.
Selecting Devices
On initialization, the OpenRGBClient
will create Device
objects
for all of your OpenRGB Devices. You can list these out by print
-ing
cli.devices
. Devices can be accessed through their index in this list,
but this is not ideal, especially for programs that will be used over a longer
period of time. This is because the device’s index could change if a new device
is added, or the order of OpenRGB’s detectors is changed. Another, more
consistent way to get a specific device is through its device type.
from openrgb.utils import DeviceType
mobo = cli.get_devices_by_type(DeviceType.MOTHERBOARD)[0]
If you have more than one device of a specific type, then you can try filtering by the devices’ metadata, name, or any other property.
Another option is to select a device(s) by name.
corsair_thing = cli.get_devices_by_name('Corsair Lighting Node Pro')[0]
# Or less exactly
cooler = cli.get_devices_by_name('wraith prism', False)[0]
# Actual name is 'AMD Wraith Prism'
Setting colors
Colors are handled by the RGBColor
object. It can be initialized from
RGB, HSV, or even HEX color values.
from openrgb.utils import RGBColor
red = RGBColor(255, 0, 0)
blue = RGBColor.fromHSV(240, 100, 100)
green = RGBColor.fromHEX('#00ff00') # The '#' symbol isn't necessary, it's just commonly attached to HEX colors
Note
Already familiar with other LED control libraries like fastLED or adafruit’s neopixel library? The effects control flow was made to be used in a similar way. Try it out and see which one you like better!
Any RGBObject
object can be set to an RGBColor
using a few
methods. RGBObject
is the parent class of basically everything.
To set an RGBObject
to a solid color, use the
set_color
function.
mobo.set_color(RGBColor(0, 255, 0))
cli.devices[0].set_color(red)
cli.devices[1].zones[0].set_color(blue)
Warning
Interacting with the SDK (setting colors, changing modes, resizing zones… ) for the same device more than once without some kind of delay in between can cause undefined behavior.
If you want to set an RGBContainer
to more than one color, use the
set_colors
function. This example assumes that the
motherboard has 8 LEDs, and sets them in a red, blue, red, blue… pattern.
mobo.set_colors([red, blue]*4)
Note
While these methods can be used for things like custom effects, it requires a little more effort to make it work quickly enough (see optimizing for speed). The effects control flow was made to be easier to use for effects that require fast changes.
Both of these methods can be used to only set part of an object. For example, for a motherboard with 8 LEDs, this would set the middle 4 to red.
mobo.set_color(red, 2, 6)
Changing Modes
A device’s modes can be found under Device.modes
, in the form of
ModeData
objects. Modes can be set for a device through the
Device.set_mode
function. The mode can be passed in via index, name, or
you can pass in the actual mode object.
mobo.set_mode(3)
mobo.set_mode('direct')
mobo.set_mode(mobo.modes[2])
Saving Modes
Some devices support saving their modes so that when you power off the device, it will remember its state when it powers back on again.
mobo.set_mode(3, save=True)
mobo.save_mode()
The first option will set a mode then save it, while the dedicated function just saves whatever the current mode is.
Resizing Zones
If you have a device with an ARGB zone, then you will probably need to resize it at some point.
mobo.zones[0].resize(35) # For a zone with 35 LEDs
Using Profiles
OpenRGB’s profiles are a way save the state of your devices after you’ve set
everything up exactly how you want it and be able to load that state easily.
Existing profiles are stored in the profiles
attribute of an OpenRGBClient
. To save a profile, first configure your
RGB setup how you want it, then run
cli.save_profile('perfection') # Saves to a new or existing profile called "perfection"
cli.save_profile(0) # Overwrites the first profile in the list
Loading profiles is equally as simple.
cli.load_profile('perfection') # Finds and loads a profile called perfection
cli.load_profile(0) # Loads the first profile in the list
If you want to you can also delete a profile.
cli.delete_profile('perfection') # Deletes a profile called perfection
cli.delete_profile(0) # Deletes the first profile in the list
If you created a new profile from OpenRGB and want to make sure your client can
see it, you can use the cli.update_profiles
function to get the latest list of profiles from the server.
Old Profile System
There are two ways to work with profiles: locally and remotely.
The old way (locally) saved profiles to a local .orp
file. The newer,
recommended way is remotely. Remotely saving a profile just tells the server to
save its current state to a profile, the same way that it would if you pressed
the “Save Profile” button on OpenRGB’s GUI. If you still want to locally save
profiles, you can do so with an extra argument.
cli.save_profile('perfection', True) # Locally saves the profile
Locally saving a profile will save a file called perfection.orp in OpenRGB’s config directory by default, so you can load the profile directly from OpenRGB’s profile list.
Loading profiles in OpenRGB-Python is equally as simple as saving them. This function will set your lights to the same as they were when they were saved. It can load profiles saved from OpenRGB itself, or OpenRGB-Python.
cli.load_profile('perfection', True) # loads a local profile
Warning
I only know where OpenRGB’s config directory is on linux and I haven’t
tested saving profiles on windows. The default directory that
OpenRGB-Python saves profiles is ~/.config/OpenRGB
. If you know
where OpenRGB’s config directory is on windows and how to reliably find it
from python, please submit a pr or come talk to me on OpenRGB’s discord
server. In the mean time, you will probably have to manually specify the
directory where you want to save or load a profile from using the
directory
argument.