API

Module contents

class openrgb.OpenRGBClient(address='127.0.0.1', port=6742, name='openrgb-python', protocol_version=None)[source]

Bases: RGBObject

This is the only class you should need to manually instantiate. It initializes the communication, gets the device information, and creates Devices, Zones, and LEDs for you.

Parameters:

address (str) – the ip address of the SDK server
port (int) – the port of the SDK server
name (str) – the string that will be displayed on the OpenRGB SDK tab’s list of clients
protocol_version (Optional[int]) – which protocol version to use

clear(): Turns all of the LEDS off

connect()[source]: Connects to the OpenRGB SDK

delete_profile(name)[source]

Deletes the selected profile

Parameters:: name (Union[str, int, Profile]) – Can be a profile’s name, index, or even the Profile itself

disconnect()[source]: Disconnects from the OpenRGB SDK

property ee_devices: A subset of the device list that only includes devices with a direct control mode. These devices are suitable to use with an effects engine.

get_devices_by_name(name, exact=True)[source]

Gets a list of any devices matching the requested name

Parameters:

name – the name of the device(s) you want to get
exact – whether to check for only a precise match or accpet a device that contains name

get_devices_by_type(type)[source]

Gets a list of devices that are the same type as requested

Parameters:: type – what type of device you want to get

load_profile(name, local=False, directory='')[source]

Loads an OpenRGB profile

Parameters:

name (Union[str, int, Profile]) – Can be a profile’s name, index, or even the Profile itself
local (bool) – Whether to load a local file or a profile from the server.
directory (str) – what directory the profile is in. Defaults to OpenRGB’s config directory for supported OS’s (Windows or Linux), or falls back to using the current working directory.

property protocol_version: The protocol version of the connected SDK server

save_profile(name, local=False, directory='')[source]

Saves the current state of all of your devices to a new or existing OpenRGB profile

Parameters:

name (Union[str, int, Profile]) – Can be a profile’s name, index, or even the Profile itself
local (bool) – Whether to load a local file or a profile on the server.
directory (str) – what directory to save the profile in. Defaults to OpenRGB’s config directory for supported OS’s (Windows or Linux), or falls back to using the current working directory.

set_color(color, fast=False)[source]

Sets the color of every device.

Parameters:

color (RGBColor) – the color to set the devices to
fast (bool) – If you care more about quickly setting colors than having correct internal state data, then set fast to True

show(fast=False, force=False)[source]

Shows all devices

Parameters:

fast (bool) – If you care more about quickly setting colors than having correct internal state data, then set fast to True
force (bool) – Sets all colors rather than trying to only set the ones that have been changed

update()[source]: Gets the current state of your devices from the SDK server, which is useful if you change something from the gui or another SDK client and need to sync up the changes.

update_plugins()[source]: Gets the list of enabled plugins from the server.

update_profiles()[source]: Gets the list of available profiles from the server.

Submodules

openrgb.network module

class openrgb.network.NetworkClient(update_callback, address='127.0.0.1', port=6742, name='openrgb-python', protocol_version=None)[source]

Bases: object

A class for interfacing with the OpenRGB SDK

Parameters:

update_callback (Callable) – the function to call when data is received
address (str) – the ip address of the SDK server
port (int) – the port of the SDK server
name (str) – the string that will be displayed on the OpenRGB SDK tab’s list of clients

check_version(packet_type)[source]

Verifies that the packet type is supported on the version we are using.

Parameters:: packet_type (PacketType) – What kind of packet is going to be sent
Raises:: utils.SDKVersionError – When a packet is unsupported

property connected: bool: Returns whether the current instance is currently connected to a server

read()[source]

Reads responses from the SDK

Raises:: utils.OpenRGBDisconnected – when it loses connection to the SDK

requestDeviceData(device)[source]

Sends the request for a device’s data

Parameters:: device (int) – the id of the device to request data for

requestDeviceNum()[source]: Requesting the number of devices from the SDK server

requestPluginList()[source]: Sends the request for the available plugins

requestProfileList()[source]: Sends the request for the available profiles

send_data(data, release_lock=True)[source]

Sends data to the SDK

Parameters:: data (bytes) – The data to send

send_header(device_id, packet_type, packet_size, release_lock=True)[source]

Sends a header to the SDK

Parameters:

device_id (int) – The id of the device to send a header for
packet_type (PacketType) – A utils.PacketType
packet_size (int) – The full size of the data to be sent after the header

start_connection()[source]: Initializes a socket, connects to the SDK, and sets the client name

stop_connection()[source]: Closes the active socket

openrgb.orgb module

class openrgb.orgb.Device(data, device_id, network_client)[source]

Bases: RGBContainer

A class to represent an RGB Device

off()[source]: Turns off device by setting the custom mode and then calling RGBObject.clear

save_mode()[source]: Saves the currently selected mode

set_color(color, fast=False)[source]

Sets the color of the device whether the current mode is per-led or mode-specific

Parameters:

colors – the list of colors, one per LED
fast (bool) – If you care more about quickly setting colors than having correct internal state data, then set fast to True (only applies when not setting a mode-specific color)

set_colors(colors, fast=False)[source]

Sets the colors of the device whether the current mode is per-led or mode-specific

Parameters:

colors – the list of colors, one per LED or per mode-specific color
fast – If you care more about quickly setting colors than having correct internal state data, then set fast to True (only applies when not setting a mode-specific color)

set_custom_mode()[source]: Sets the mode to whatever the device supports that provides the most granular control

set_mode(mode, save=False)[source]

Sets the device’s mode

Parameters:: mode (Union[str, int, ModeData]) – the name, id, or the ModeData object itself to set as the mode

class openrgb.orgb.LED(data, color, led_id, device_id, network_client)[source]

Bases: RGBObject

A class to represent individual LEDs

set_color(color, fast=False)[source]

Sets the color of the LED

Parameters:

color (RGBColor) – the color to set the LED to
fast (bool) – If you care more about quickly setting colors than having correct internal state data, then set fast to True

class openrgb.orgb.OpenRGBClient(address='127.0.0.1', port=6742, name='openrgb-python', protocol_version=None)[source]

Bases: RGBObject

This is the only class you should need to manually instantiate. It initializes the communication, gets the device information, and creates Devices, Zones, and LEDs for you.

Parameters:

address (str) – the ip address of the SDK server
port (int) – the port of the SDK server
name (str) – the string that will be displayed on the OpenRGB SDK tab’s list of clients
protocol_version (Optional[int]) – which protocol version to use

connect()[source]: Connects to the OpenRGB SDK

delete_profile(name)[source]

Deletes the selected profile

Parameters:: name (Union[str, int, Profile]) – Can be a profile’s name, index, or even the Profile itself

disconnect()[source]: Disconnects from the OpenRGB SDK

property ee_devices: A subset of the device list that only includes devices with a direct control mode. These devices are suitable to use with an effects engine.

get_devices_by_name(name, exact=True)[source]

Gets a list of any devices matching the requested name

Parameters:

name – the name of the device(s) you want to get
exact – whether to check for only a precise match or accpet a device that contains name

get_devices_by_type(type)[source]

Gets a list of devices that are the same type as requested

Parameters:: type – what type of device you want to get

load_profile(name, local=False, directory='')[source]

Loads an OpenRGB profile

Parameters:

name (Union[str, int, Profile]) – Can be a profile’s name, index, or even the Profile itself
local (bool) – Whether to load a local file or a profile from the server.
directory (str) – what directory the profile is in. Defaults to OpenRGB’s config directory for supported OS’s (Windows or Linux), or falls back to using the current working directory.

property protocol_version: The protocol version of the connected SDK server

save_profile(name, local=False, directory='')[source]

Saves the current state of all of your devices to a new or existing OpenRGB profile

Parameters:

name (Union[str, int, Profile]) – Can be a profile’s name, index, or even the Profile itself
local (bool) – Whether to load a local file or a profile on the server.
directory (str) – what directory to save the profile in. Defaults to OpenRGB’s config directory for supported OS’s (Windows or Linux), or falls back to using the current working directory.

set_color(color, fast=False)[source]

Sets the color of every device.

Parameters:

color (RGBColor) – the color to set the devices to
fast (bool) – If you care more about quickly setting colors than having correct internal state data, then set fast to True

show(fast=False, force=False)[source]

Shows all devices

Parameters:

fast (bool) – If you care more about quickly setting colors than having correct internal state data, then set fast to True
force (bool) – Sets all colors rather than trying to only set the ones that have been changed

update()[source]: Gets the current state of your devices from the SDK server, which is useful if you change something from the gui or another SDK client and need to sync up the changes.

update_plugins()[source]: Gets the list of enabled plugins from the server.

update_profiles()[source]: Gets the list of available profiles from the server.

class openrgb.orgb.Segment(data, id, parent)[source]

Bases: RGBContainer

A class to represent a segment

set_color(color, fast=False)[source]

Sets the color

Parameters:: color (RGBColor) – the color to set

set_colors(colors, fast=False)[source]

Sets mutliple colors

Parameters:: colors – A list of colors to set

class openrgb.orgb.Zone(data, zone_id, device_id, network_client)[source]

Bases: RGBContainer

A class to represent a zone

resize(size)[source]

Resizes the zone. Required to control addressable leds in Direct mode.

Parameters:: size (int) – the number of leds in the zone

set_color(color, fast=False)[source]

Sets the zone’s color

Parameters:

color (RGBColor) – the color to set the LEDs to
fast (bool) – If you care more about quickly setting colors than having correct internal state data, then set fast to True

set_colors(colors, fast=False)[source]

Sets the LEDs’ colors in the zone

Parameters:

colors – the list of colors, one per LED
fast – If you care more about quickly setting colors than having correct internal state data, then set fast to True

openrgb.utils module

class openrgb.utils.ControllerData(name, metadata, device_type, leds, zones, modes, colors, active_mode)[source]

Bases: object

active_mode: int

colors: list[RGBColor]

device_type: DeviceType

leds: list[LEDData]

metadata: MetaData

modes: list[ModeData]

name: str

pack(version)[source]

Packs itself into a bytes ready to be sent to the SDK or saved in a profile

Return type:: bytes
Returns:: raw data ready to be sent or saved

classmethod unpack(raw_data, version, start=0)[source]

Unpacks the raw bytes received from the SDK into a ControllerData dataclass

Parameters:: data – The raw data from a response to a request for device data
Return type:: ControllerData
Returns:: A ControllerData dataclass ready to pass into the OpenRGBClient’s calback function

zones: list[ZoneData]

exception openrgb.utils.ControllerParsingError[source]: Bases: ValueError

class openrgb.utils.DeviceType(value)[source]

Bases: IntEnum

An enumeration.

ACCESSORY = 17

CASE = 15

COOLER = 3

DRAM = 1

GAMEPAD = 10

GPU = 2

HEADSET = 8

HEADSET_STAND = 9

KEYBOARD = 5

KEYPAD = 18

LEDSTRIP = 4

LIGHT = 11

MICROPHONE = 16

MOTHERBOARD = 0

MOUSE = 6

MOUSEMAT = 7

SPEAKER = 12

STORAGE = 14

UNKNOWN = 19

VIRTUAL = 13

class openrgb.utils.LEDData(name, value)[source]

Bases: object

name: str

pack(version)[source]

Packs itself into a bytes ready to be sent to the SDK or saved in a profile

Return type:: bytes
Returns:: raw data ready to be sent or saved

classmethod unpack(data, version, *args)[source]

Creates a new LEDData object from raw bytes

Parameters:: data (Iterator[int]) – the raw bytes from the SDK
Return type:: LEDData

value: int

class openrgb.utils.LocalProfile(controllers)[source]

Bases: object

A dataclass to load, store, and pack the data found in an OpenRGB profile file.

controllers: list[ControllerData]

pack()[source]

Return type:: bytes

classmethod unpack(profile)[source]

Return type:: LocalProfile

class openrgb.utils.MetaData(vendor, description, version, serial, location)[source]

Bases: object

description: str

location: str

pack(version)[source]

Packs itself into a bytes ready to be sent to the SDK or saved in a profile

Return type:: bytes
Returns:: raw data ready to be sent or saved

serial: str

classmethod unpack(data, version, *args)[source]

Unpacks the raw data into a MetaData object

Parameters:: data (Iterator[int]) – The raw byte data to unpack
Return type:: MetaData

vendor: Optional[str]

version: str

class openrgb.utils.ModeColors(value)[source]

Bases: IntEnum

An enumeration.

MODE_SPECIFIC = 2

NONE = 0

PER_LED = 1

RANDOM = 3

class openrgb.utils.ModeData(id, name, value, flags, speed_min, speed_max, brightness_min, brightness_max, colors_min, colors_max, speed, brightness, direction, color_mode, colors)[source]

Bases: object

brightness: Optional[int]

brightness_max: Optional[int]

brightness_min: Optional[int]

color_mode: ModeColors

colors: Optional[list[RGBColor]]

colors_max: Optional[int]

colors_min: Optional[int]

direction: Optional[ModeDirections]

flags: ModeFlags

id: int

name: str

pack(version)[source]

Packs itself into a bytes ready to be sent to the SDK or saved in a profile

Return type:: bytes
Returns:: raw data ready to be sent or saved

speed: Optional[int]

speed_max: Optional[int]

speed_min: Optional[int]

classmethod unpack(data, version, index=0)[source]

Creates a new ModeData object from raw bytes

Parameters:

data (Iterator[int]) – the raw bytes from the SDK
index (int) – which mode this is

Return type:

ModeData

validate(version)[source]: Tests the values of the mode data and raises a ValueError if the validation fails

value: int

class openrgb.utils.ModeDirections(value)[source]

Bases: IntEnum

An enumeration.

DOWN = 3

HORIZONTAL = 4

LEFT = 0

RIGHT = 1

UP = 2

VERTICAL = 5

class openrgb.utils.ModeFlags(value)[source]

Bases: IntFlag

An enumeration.

HAS_BRIGHTNESS = 16

HAS_DIRECTION_HV = 8

HAS_DIRECTION_LR = 2

HAS_DIRECTION_UD = 4

HAS_MODE_SPECIFIC_COLOR = 64

HAS_PER_LED_COLOR = 32

HAS_RANDOM_COLOR = 128

HAS_SPEED = 1

exception openrgb.utils.OpenRGBDisconnected[source]: Bases: ConnectionError

class openrgb.utils.PacketType(value)[source]

Bases: IntEnum

An enumeration.

DEVICE_LIST_UPDATED = 100

PLUGIN_SPECIFIC = 201

REQUEST_CONTROLLER_COUNT = 0

REQUEST_CONTROLLER_DATA = 1

REQUEST_DELETE_PROFILE = 153

REQUEST_LOAD_PROFILE = 152

REQUEST_PLUGIN_LIST = 200

REQUEST_PROFILE_LIST = 150

REQUEST_PROTOCOL_VERSION = 40

REQUEST_SAVE_PROFILE = 151

RGBCONTROLLER_RESIZEZONE = 1000

RGBCONTROLLER_SAVEMODE = 1102

RGBCONTROLLER_SETCUSTOMMODE = 1100

RGBCONTROLLER_UPDATELEDS = 1050

RGBCONTROLLER_UPDATEMODE = 1101

RGBCONTROLLER_UPDATESINGLELED = 1052

RGBCONTROLLER_UPDATEZONELEDS = 1051

SET_CLIENT_NAME = 50

class openrgb.utils.Plugin(name, description, version, id, sdk_version)[source]

Bases: object

description: str

id: int

name: str

pack()[source]

sdk_version: int

classmethod unpack(data, version, *args)[source]

Return type:: Plugin

version: str

class openrgb.utils.Profile(name)[source]

Bases: object

A simple dataclass to parse profiles from the server.

name: str

pack()[source]

Return type:: bytes

classmethod unpack(data, version, *args)[source]

Return type:: Profile

class openrgb.utils.RGBColor(red, green, blue)[source]

Bases: object

blue: int

classmethod fromHEX(hex)[source]

Creates a RGBColor object from a hex color string

Return type:: RGBColor

classmethod fromHSV(hue, saturation, value)[source]

Creates a RGBColor object from HSV values using colorsys

Return type:: RGBColor

green: int

pack(version=0)[source]

Packs itself into a bytes ready to be sent to the SDK or saved in a profile

Return type:: bytes
Returns:: raw data ready to be sent or saved

red: int

classmethod unpack(data, version, *args)[source]

Unpacks an RGBColor object from bytes

Return type:: RGBColor
Returns:: an RGBColor object

class openrgb.utils.RGBContainer[source]

Bases: RGBObject

A parent class for RGBObjects that can control more than one LED like the Device class or the Zone class.

set_colors(colors, fast=False)[source]

Sets mutliple colors

Parameters:: colors – A list of colors to set

show(fast=False, force=False)[source]

Applies changes in the color attribute

Parameters:

fast (bool) – Whether or not update the device on each call
force (bool) – If True, the function will update every led, regardless of previous state.

class openrgb.utils.RGBObject[source]

Bases: object

A parent class that includes a few generic functions that use the implementation provided by the children.

clear()[source]: Turns all of the LEDS off

set_color(color, fast=False)[source]

Sets the color

Parameters:: color (RGBColor) – the color to set

update()[source]: Gets the current status from the SDK server, ensuring a correct internal state.

exception openrgb.utils.SDKVersionError[source]: Bases: NotImplementedError

class openrgb.utils.SegmentData(name, segment_type, start_idx, leds_count)[source]

Bases: object

leds_count: int

name: str

pack(version)[source]

Packs itself into a bytes ready to be sent to the SDK or saved in a profile

Return type:: bytes
Returns:: raw data ready to be sent or saved

segment_type: ZoneType

start_idx: int

classmethod unpack(data, version, *args)[source]

Unpacks the raw data into a SegmentData object

Parameters:: data (Iterator[int]) – The raw byte data to unpack
Return type:: SegmentData

class openrgb.utils.ZoneData(name, zone_type, leds_min, leds_max, num_leds, mat_height, mat_width, matrix_map=None, segments=None, leds=<factory>, colors=<factory>, start_idx=0)[source]

Bases: object

colors: list[RGBColor]

leds: list[LEDData]

leds_max: int

leds_min: int

mat_height: Optional[int]

mat_width: Optional[int]

matrix_map: Optional[list[list[Optional[int]]]] = None

name: str

num_leds: int

pack(version)[source]

Packs itself into a bytes ready to be sent to the SDK or saved in a profile

Return type:: bytes
Returns:: raw data ready to be sent or saved

segments: Optional[list[SegmentData]] = None

start_idx: int = 0

classmethod unpack(data, version, *args)[source]

Unpacks the raw data into a ZoneData object

Parameters:: data (Iterator[int]) – The raw byte data to unpack
Return type:: ZoneData

zone_type: ZoneType

class openrgb.utils.ZoneType(value)[source]

Bases: IntEnum

An enumeration.

LINEAR = 1

MATRIX = 2

SINGLE = 0

openrgb.utils.pack_list(things, version)[source]

Packs a list of things using the things’ .pack() methods

Parameters:: things (list) – a list of things to pack
Return type:: bytes
Returns:: bytes ready to be used

openrgb.utils.pack_string(string)[source]

Packs a string into bytes

Parameters:: string (str) – the string to pack
Return type:: bytes
Returns:: bytes ready to be used

openrgb.utils.parse_list(kind, data, version)[source]

Parses a list of objects and returns them

Parameters:

kind (object) – the class that the list consists of
data (Iterator[int]) – the raw data to parse
start – the location in the data to start parsing

Return type:

list

openrgb.utils.parse_string(data)[source]

Parses a string based on a size.

Parameters:: data (Iterator[int]) – the raw data to parse
Return type:: str
Returns:: A parsed string

openrgb.utils.parse_var(type, data)[source]

Return type:: Any