OpenRGB-Python

https://openrgb-python.readthedocs.io/en/latest
Admin
OpenRGB-Python is a Python library that provides an interface to interact with the OpenRGB SDK,...
Tokens:30,801
Snippets:180
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Access OpenRGB Devices

Source: https://openrgb-python.readthedocs.io/en/latest/pages/effects

This snippet demonstrates how to initialize the OpenRGB client and access both all available devices and those suitable for direct control (ee_devices). It's a basic setup for interacting with OpenRGB.

```python
from openrgb import OpenRGBClient

cli = OpenRGBClient()

print(cli.devices)
print(cli.ee_devices)

```

--------------------------------

### Setting Colors on Devices and Zones in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/usage

Colors are applied to RGBObjects like devices or zones using set_color for single colors or set_colors for multiples, with optional start/end indices for partial zones. Depends on initialized client and RGBColor; inputs include color objects and optional indices, updates device state immediately. Warning: Multiple rapid interactions without delays can cause undefined behavior; suitable for basic setups but effects need optimization for speed.

```python
mobo.set_color(RGBColor(0, 255, 0))
cli.devices[0].set_color(red)
cli.devices[1].zones[0].set_color(blue)

mobo.set_colors([red, blue]*4)

mobo.set_color(red, 2, 6)
```

--------------------------------

### Get Devices by Name in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Returns a list of devices matching the specified name. Supports exact or partial name matching.

```python
def get_devices_by_name(self, name: str, exact: bool = True) -> list[Device]:
    '''
    Gets a list of any devices matching the requested name

    :param name: the name of the device(s) you want to get
    :param exact: whether to check for only a precise match or accpet a device that contains name
    '''
    if exact:
        return [device for device in self.devices if device.name == name]
    return [device for device in self.devices if name.lower() in device.name.lower()]
```

--------------------------------

### Create Rainbow Effect on Linear Zone

Source: https://openrgb-python.readthedocs.io/en/latest/pages/effects

This example shows how to create a rainbow effect on a linear LED zone. It calculates color spectrum steps based on the number of LEDs and assigns HSV color values to each LED, then applies the changes. Requires OpenRGBClient and RGBColor/ZoneType from openrgb.utils.

```python
from openrgb import OpenRGBClient
from openrgb.utils import RGBColor, ZoneType

cli = OpenRGBClient()

# finding a linear zone
zone = next(z for dev in cli.ee_devices for z in dev.zones if z.type == ZoneType.LINEAR)
# dividing the color spectrum by number of LEDs in the zone
step = int(360/len(zone.colors))
# Setting the zones colors to the entire spectrum of the rainbow
for i, hue in enumerate(range(0, 360, step)):
    zone.colors[i] = RGBColor.fromHSV(hue, 100, 100)
zone.show()

```

--------------------------------

### Get Devices by Type in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Returns a list of devices matching the specified device type. Useful for filtering devices by category.

```python
def get_devices_by_type(self, type: utils.DeviceType) -> list[Device]:
    '''
    Gets a list of devices that are the same type as requested

    :param type: what type of device you want to get
    '''
    return [device for device in self.devices if device.type == type]
```

--------------------------------

### Saving Device Modes in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/usage

Modes are saved to persist state across power cycles on supported devices, using set_mode with save=True or dedicated save_mode. Requires device support for persistence; inputs current or specified mode. Limitations: Not all devices support saving; ensures state retention without additional setup.

```python
mobo.set_mode(3, save=True)
mobo.save_mode()
```

--------------------------------

### Set Protocol Version in OpenRGB Python

Source: https://openrgb-python.readthedocs.io/en/latest/pages/advanced

This code shows how to set the SDK protocol version in OpenRGB-Python either at client initialization or during usage. It depends on the OpenRGB-Python library being installed and requires an integer protocol version as input. Output is an updated client instance or a raised ValueError if the version exceeds supported limits. Limitation includes a potential 1-second delay with mismatched client/server versions.

```python
# To change the protocol version at initialization
cli = OpenRGBClient(protocol_version=0)

# To change the protocol version during usage
cli.protocol_version = 1

```

--------------------------------

### Initialize OpenRGB Client in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Initializes the OpenRGB client with network settings and callback functions. Sets up device and profile lists.

```python
self.profiles: list[utils.Profile] = []
self.plugins: list[ORGBPlugin] = []
self.comms = NetworkClient(
    self._callback, address, port, name, protocol_version)
self.address = address
self.port = port
self.name = name
self.update()
```

--------------------------------

### Initialize Device in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

This constructor initializes a Device object with controller data, setting up LEDs, zones, and metadata. It processes lists for LEDs and zones, creating or updating objects. Dependencies include utils for ControllerData and NetworkClient. Input is ControllerData, device_id, and NetworkClient; initializes all internal lists.

```python
def __init__(self, data: utils.ControllerData, device_id: int, network_client: NetworkClient):
    self.leds: list[LED] = [None for i in data.leds]  # type: ignore
    self.zones: list[Zone] = [None for i in data.zones]  # type: ignore
    self.id = device_id
    self.device_id = device_id
    self.comms = network_client
    self._update(data)
```

--------------------------------

### SegmentData Class - OpenRGB Python

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Represents data for a segment within a device, including its name, type, start index, and LED count. Provides methods for packing and unpacking segment data.

```python
class _openrgb.utils.SegmentData(_name_, _segment_type_, _start_idx_, _leds_count_):
    Bases: `object`

    leds_count: `int`
    name: `str`

    def pack(_version):
        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
        pass

    segment_type: `ZoneType`
    start_idx: `int`

    @classmethod
    def _unpack(_data_, _version_, *_args_):
        Unpacks the raw data into a SegmentData object
        Parameters:
            **data** (`Iterator`[`int`]) – The raw byte data to unpack
        Return type:
            `SegmentData`
        pass
```

--------------------------------

### Initialize OpenRGB Client and List Devices (Python)

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/effects

Initializes the OpenRGB client and prints lists of all available devices and effect-enabled devices. Requires the 'openrgb' library.

```python
from openrgb import OpenRGBClient

cli = OpenRGBClient()

print(cli.devices)
print(cli.ee_devices)
```

--------------------------------

### Initialize OpenRGB Client in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Initializes the OpenRGB client, establishing communication with the SDK server. It handles device discovery and the creation of corresponding Device, Zone, and LED objects. It takes optional parameters for server address, port, client name, and protocol version.

```python
class OpenRGBClient(utils.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.
    '''

    def __init__(self, address: str = "127.0.0.1", port: int = 6742, name: str = "openrgb-python", protocol_version: Optional[int] = None):
        '''
        :param address: the ip address of the SDK server
        :param port: the port of the SDK server
        :param name: the string that will be displayed on the OpenRGB SDK tab's list of clients
        :param protocol_version: which protocol version to use
        '''
        self.device_num = 0
        self.devices: list[Device] = []
```

--------------------------------

### Get Protocol Version - Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Retrieves the current protocol version used by the connected OpenRGB SDK server. This is useful for ensuring compatibility between the client and server. The version is accessed via an internal communication object.

```python
    @property
    def protocol_version(self):
        '''The protocol version of the connected SDK server'''
        return self.comms._protocol_version

```

--------------------------------

### OpenRGBClient Initialization

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Initializes the OpenRGBClient, establishing communication with the OpenRGB SDK server. This class is the primary interface for controlling RGB devices.

```APIDOC
## Class: OpenRGBClient

### Description
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
#### Initialization Parameters
- **address** (str) - The IP address of the SDK server. Defaults to '127.0.0.1'.
- **port** (int) - The port of the SDK server. Defaults to 6742.
- **name** (str) - The string that will be displayed on the OpenRGB SDK tab’s list of clients. Defaults to 'openrgb-python'.
- **protocol_version** (Optional[int]) - Which protocol version to use. Defaults to None.

### Example Usage
```python
from openrgb import OpenRGBClient

client = OpenRGBClient(address='127.0.0.1', port=6742)
```
```

--------------------------------

### Get Direct Control Devices - Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Filters the list of all connected devices to return only those that support direct control mode. These devices are suitable for use with effects engines, providing a focused list for advanced control scenarios. It iterates through devices and their modes.

```python
    @property
    def ee_devices(self):
        '''
        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.
        '''
        return [dev for dev in self.devices for mode in dev.modes if mode.name.lower() == 'direct']

```

--------------------------------

### Optimize OpenRGB-Python for speed

Source: https://openrgb-python.readthedocs.io/en/latest/pages/advanced

Shows how to minimize SDK calls for faster light updates. Uses set_colors and show methods with optimized color arrays.

```python
cli.devices[0].set_colors(
    [RGBColor(0, 0, 255)]*3 \
    + [RGBColor(255, 0, 0)] \
    + [RGBColor(0, 255, 0)]*4
)
```

```python
cli.devices[0].colors = [RGBColor(255, 0, 0)]*8
cli.devices[0].colors[:3] = [RGBColor(0, 0, 255)]*3
cli.devices[0].colors[4:8] = [RGBColor(0, 255, 0)]*4
cli.devices[0].show()
```

--------------------------------

### Initializing OpenRGBClient in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/usage

The OpenRGBClient is initialized to connect to the OpenRGB SDK server for controlling RGB devices. It requires the openrgb library and accepts optional parameters for host IP, port (default 8000), and client name. Outputs a client object for further interactions; assumes local SDK by default but supports remote connections.

```python
from openrgb import OpenRGBClient
cli = OpenRGBClient()

cli = OpenRGBClient('192.168.1.111', 8000, 'My client!')
```

--------------------------------

### OpenRGBClient Methods

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Provides a collection of methods for managing connections, devices, profiles, and colors within the OpenRGB environment.

```APIDOC
## OpenRGBClient Methods

### `clear()`

#### Description
Turns all of the LEDs off.

#### Method
`clear()`

### `connect()`

#### Description
Connects to the OpenRGB SDK.

#### Method
`connect()`

### `delete_profile(name)`

#### Description
Deletes the selected profile.

#### Method
`delete_profile(name: Union[str, int, Profile])`

#### Parameters
- **name** (Union[str, int, Profile]) - Can be a profile’s name, index, or even the Profile itself.

### `disconnect()`

#### Description
Disconnects from the OpenRGB SDK.

#### Method
`disconnect()`

### `get_devices_by_name(name, exact=True)`

#### Description
Gets a list of any devices matching the requested name.

#### Method
`get_devices_by_name(name: str, exact: bool = True)`

#### Parameters
- **name** (str) - The name of the device(s) you want to get.
- **exact** (bool) - Whether to check for only a precise match or accept a device that contains the name. Defaults to True.

### `get_devices_by_type(type)`

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

#### Method
`get_devices_by_type(type: str)`

#### Parameters
- **type** (str) - What type of device you want to get.

### `load_profile(name, local=False, directory='')`

#### Description
Loads an OpenRGB profile.

#### Method
`load_profile(name: Union[str, int, Profile], local: bool = False, directory: str = '')`

#### 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. Defaults to False.
- **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.

### `save_profile(name, local=False, directory='')`

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

#### Method
`save_profile(name: Union[str, int, Profile], local: bool = False, directory: str = '')`

#### 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. Defaults to False.
- **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)`

#### Description
Sets the color of every device.

#### Method
`set_color(color: RGBColor, fast: bool = False)`

#### 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`. Defaults to False.

### `show(fast=False, force=False)`

#### Description
Shows all devices.

#### Method
`show(fast: bool = False, force: bool = False)`

#### Parameters
- **fast** (bool) - If you care more about quickly setting colors than having correct internal state data, then set `fast` to `True`. Defaults to False.
- **force** (bool) - Sets all colors rather than trying to only set the ones that have been changed. Defaults to False.

### `update()`

#### Description
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.

#### Method
`update()`

### `update_plugins()`

#### Description
Gets the list of enabled plugins from the server.

#### Method
`update_plugins()`

### `update_profiles()`

#### Description
Gets the list of available profiles from the server.

#### Method
`update_profiles()`

```

--------------------------------

### Device Display API

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Shows all connected devices with optional performance optimizations. Allows quick color setting with optional fast mode and force update flags.

```APIDOC
## Shows all devices

### Description
Displays all connected RGB devices. Provides options to optimize performance by skipping internal state synchronization.

### Method
GET

### Endpoint
/devices

### Parameters
#### Query Parameters
- **fast** (`bool`) - Optional - If true, prioritizes quick color setting over correct internal state data
- **force** (`bool`) - Optional - If true, sets all colors rather than only changed ones

### Request Example
```
GET /devices?fast=true&force=false
```

### Response
#### Success Response (200)
- **devices** (array) - List of connected RGB devices

#### Response Example
{
  "devices": [
    {
      "id": 1,
      "name": "Corsair RAM",
      "type": "DRAM"
    }
  ]
}
```

--------------------------------

### Loading Profiles with OpenRGB Python Client

Source: https://openrgb-python.readthedocs.io/en/latest/pages/usage

Loads a saved profile to restore RGB device states, supporting both remote and local profiles from OpenRGB GUI or Python. Depends on OpenRGBClient; inputs are profile name/index and optional local flag. Sets device lights accordingly; local loads from default config directory on Linux.

```python
cli.load_profile('perfection') # Finds and loads a profile called perfection
cli.load_profile(0) # Loads the first profile in the list
```

```python
cli.load_profile('perfection', True) # loads a local profile
```

--------------------------------

### Compactly Set Colors in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/advanced

This snippet provides a more concise way to set multiple colors in a device, reducing the number of SDK calls.

```python
cli.devices[0].modes[2].colors = [RGBColor(255, 0, 0), RGBColor(0, 0, 255)]
cli.devices[0].set_mode(2)
```

--------------------------------

### Plugin Dataclass for Plugin Information

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

A dataclass to store plugin information including name, description, version, ID, and SDK version. Includes methods for unpacking plugin data from an iterator of integers.

```python
@dataclass
class Plugin:
    '''

    '''
    name: str
    description: str
    version: str
    id: int
    sdk_version: int


    def pack(self):
        pass


    @classmethod
    def unpack(cls, data: Iterator[int], version: int, *args) -> Plugin:
        name = parse_string(data)
        description = parse_string(data)
        version_str = parse_string(data)
        id = parse_var('i', data)
        sdk_version = parse_var('I', data)
        return cls(
            name,
            description,
            version_str,
            id,
            sdk_version
        )
```

--------------------------------

### Resizing Zones in OpenRGB Python

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/usage

ARGB zones on devices are resized to match actual LED count using resize on Zone objects. Purpose is to align zone size with hardware for accurate control; inputs integer LED count. Depends on device with zones; ensures proper color application across all LEDs.

```python
mobo.zones[0].resize(35)
```

--------------------------------

### Saving Profiles with OpenRGB Python Client

Source: https://openrgb-python.readthedocs.io/en/latest/pages/usage

Saves the current RGB device configuration to a profile, either remotely on the server or locally to a file. Requires an initialized OpenRGBClient instance. Inputs are profile name (string) or index (int), and optional boolean for local saving; outputs none, but local saves to ~/.config/OpenRGB by default on Linux.

```python
cli.save_profile('perfection') # Saves to a new or existing profile called "perfection"
cli.save_profile(0) # Overwrites the first profile in the list
```

```python
cli.save_profile('perfection', True) # Locally saves the profile
```

--------------------------------

### Resize ARGB Zones in Python

Source: https://openrgb-python.readthedocs.io/en/latest/pages/usage

Adjusts the LED count for variable ARGB zones. Updates zone configuration for effects. Takes new integer LED count; requires zone supports resizing. Verify device capabilities to prevent errors.

```python
mobo.zones[0].resize(35) # For a zone with 35 LEDs
```

--------------------------------

### LocalProfile Dataclass for OpenRGB Profile Handling

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

A dataclass to load, store, and pack data from OpenRGB profile files. Includes methods for packing profile data into bytes and unpacking from binary input.

```python
@dataclass
class LocalProfile:
    '''
    A dataclass to load, store, and pack the data found in an OpenRGB profile file.
    '''
    controllers: list[ControllerData]


    def pack(self) -> bytes:
        data = bytes()
        data += struct.pack("16sI", b'OPENRGB_PROFILE\x00', 1)
        for dev in self.controllers:
            data += dev.pack(0)
        return data


    @classmethod
    def unpack(cls, profile: BinaryIO) -> LocalProfile:
        header = profile.read(16 + struct.calcsize("I"))
        if struct.unpack("16s", header[:16])[0] != b"OPENRGB_PROFILE\x00":
            raise ValueError("The file is not an OpenRGB profile")
        version = struct.unpack("I", header[16:])[0]
        if version == 1:
            version = 0
        controllers = []
        while True:
            d = profile.read(struct.calcsize("I"))
            if len(d) < struct.calcsize("I"):
                break
            size = struct.unpack("I", d)[0]
            profile.seek(profile.tell() - struct.calcsize("I"))
            new_data = ControllerData.unpack(profile.read(size), version)
            controllers.append(new_data)
        return cls(controllers)
```

--------------------------------

### RGBContainer Class for Multi-LED Control

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

A parent class for RGBObjects that can control multiple LEDs. Includes methods for setting multiple colors and applying color changes with options for fast update and force update.

```python
class RGBContainer(RGBObject):
    '''
    A parent class for RGBObjects that can control more than one LED like the
    :any:`Device` class or the :any:`Zone` class.
    '''

    def __init__(self):
        self.colors: list[RGBColor] = []
        self._colors: list[RGBColor] = []
        self.leds: list = []


    def set_colors(self, colors: list[RGBColor], fast: bool = False):
        '''
        Sets mutliple colors

        :param colors: A list of colors to set
        '''
        pass


    def show(self, fast: bool = False, force: bool = False):
        '''
        Applies changes in the color attribute

        :param fast: Whether or not update the device on each call
        :param force: If True, the function will update every led, regardless of previous state.
        '''
        if len(self.colors) > len(self._colors):
            raise ValueError(f"`self.colors` is longer than expected length `{len(self._colors)}`")
        elif len(self.colors) < len(self._colors):
            raise ValueError(f"`self.colors` is shorter than expected length `{len(self._colors)}`")
        changed = [(i, color) for i, color in enumerate(self.colors) if color != self._colors[i]]
        if force:
            self.set_colors(self.colors, fast=True)
        elif len(changed) == 0:
            return
        elif len(changed) == 1:
            self.leds[changed[0][0]].set_color(changed[0][1], fast=True)
        elif len(changed) > 1:
            self.set_colors(self.colors, fast=True)
        self._colors = self.colors[:]
        if not fast:
            self.update()
```

--------------------------------

### Connect to OpenRGB SDK - Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Establishes a connection to the OpenRGB SDK server. This is a prerequisite for controlling any RGB devices through the SDK. It relies on an internal communication object to manage the connection.

```python
    def connect(self):
        '''Connects to the OpenRGB SDK'''
        self.comms.start_connection()

```

--------------------------------

### Pack ModeData into binary bytes in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

Serializes ModeData objects into length-prefixed binary format for OpenRGB protocol. Performs version-aware packing with conditional fields for brightness support. Handles optional values with default zero padding. Validates data before packing and prepends total length for protocol compliance. Returns complete binary payload ready for transmission.

```python
def pack(self, version: int) -> bytes:
        '''
        Packs itself into a bytes ready to be sent to the SDK or saved in a profile

        :returns: raw data ready to be sent or saved
        '''
        self.validate(version)
        data = struct.pack("i", self.id)
        data += pack_string(self.name)
        data += struct.pack('i', self.value)
        data += struct.pack('I', self.flags)
        data += struct.pack('I', self.speed_min if self.speed_min is not None else 0)
        data += struct.pack('I', self.speed_max if self.speed_max is not None else 0)
        if version >= 3:
            data += struct.pack('I', self.brightness_min if self.brightness_min is not None else 0)
            data += struct.pack('I', self.brightness_max if self.brightness_max is not None else 0)
        data += struct.pack('I', self.colors_min if self.colors_min is not None else 0)
        data += struct.pack('I', self.colors_max if self.colors_max is not None else 0)
        data += struct.pack('I', self.speed if self.speed is not None else 0)
        if version >= 3:
            data += struct.pack('I', self.brightness if self.brightness is not None else 0)
        data += struct.pack('I', self.direction if self.direction is not None else 0)
        data += struct.pack('I', self.color_mode)

        data += pack_list(self.colors if self.colors is not None else [], version)
        data = struct.pack("I", len(data) + struct.calcsize("I")) + data
        return data
```

--------------------------------

### Resize Zone in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

This method resizes a zone to a specified number of LEDs, required for Direct mode control of addressable LEDs. It sends a resize command via network communication using struct packing. Dependencies include utils for packet types. Input is an integer size; no output beyond sending the command and updating internal state.

```python
self.comms.send_header(
    self.device_id,
    utils.PacketType.RGBCONTROLLER_RESIZEZONE,
    struct.calcsize("ii")
)
self.comms.send_data(struct.pack("ii", self.id, size))
self.update()
```

--------------------------------

### RGBContainer Methods - OpenRGB Python

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Provides methods for controlling multiple LEDs, such as setting a list of colors or applying changes. This class serves as a parent for devices and zones.

```python
class _openrgb.utils.RGBContainer:
    Bases: `RGBObject`
    A parent class for RGBObjects that can control more than one LED like the `Device` class or the `Zone` class.

    def set_colors(_colors_, _fast=False):
        Sets mutliple colors
        Parameters:
            **colors** – A list of colors to set

    def show(_fast=False, _force=False):
        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.
```

--------------------------------

### Profile Dataclass for Server Profile Parsing

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

A simple dataclass to parse profiles from the server. Includes methods for packing profile name into bytes and unpacking from an iterator of integers.

```python
@dataclass
class Profile:
    '''
    A simple dataclass to parse profiles from the server.
    '''
    name: str


    def pack(self) -> bytes:
        return bytes(f"{self.name}\0", 'utf-8')


    @classmethod
    def unpack(cls, data: Iterator[int], version: int, *args) -> Profile:
        s = parse_string(data)
        return cls(s)
```

--------------------------------

### Selecting Devices in OpenRGB Python

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/usage

Devices are selected from the client using type, name, or index for consistent access despite changes in device order. Depends on openrgb.utils for DeviceType enum; inputs include device type or partial/exact name, outputs a list of Device objects. Limitations include potential index shifts if device list changes.

```python
from openrgb.utils import DeviceType

mobo = cli.get_devices_by_type(DeviceType.MOTHERBOARD)[0]

corsair_thing = cli.get_devices_by_name('Corsair Lighting Node Pro')[0]
cooler = cli.get_devices_by_name('wraith prism', False)[0]
```

--------------------------------

### Creating RGBColor Objects in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/usage

RGBColor objects represent colors for setting on devices and zones, supporting RGB, HSV, or HEX inputs. Requires openrgb.utils import; purpose is to define uniform color values across LEDs. No specific outputs beyond the color object; HEX input tolerates optional '#' prefix.

```python
from openrgb.utils import RGBColor
red = RGBColor(255, 0, 0)
blue = RGBColor.fromHSV(240, 100, 100)
green = RGBColor.fromHEX('#00ff00')
```

--------------------------------

### Zone.resize()

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Resizes an addressable zone, required for Direct mode LED control.

```APIDOC
## Zone.resize()

### Description
Resizes a zone to control addressable LEDs in Direct mode.

### Method
PUT

### Endpoint
/zone/{zone_id}/resize

### Parameters
#### Path Parameters
- **zone_id** (int) - Required - The ID of the zone to resize

#### Request Body
- **size** (`int`) - Required - The number of LEDs in the zone

### Request Example
{
  "size": 24
}

### Response
#### Success Response (200)
- **status** (string) - Resize completion status

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Load OpenRGB Profile in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Loads an OpenRGB profile from either the server or a local file. Handles different operating system configurations.

```python
def load_profile(self, name: Union[str, int, utils.Profile], local: bool = False, directory: str = ''):
    '''
    Loads an OpenRGB profile

    :param name: Can be a profile's name, index, or even the Profile itself
    :param local: Whether to load a local file or a profile from the server.
    :param directory: 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.
    '''
    if local:
        assert isinstance(name, str)
        if directory == '':
            if platform.system() == "Linux":
                directory = environ['HOME'].rstrip(
                    "/") + "/.config/OpenRGB"
            elif platform.system() == "Windows":
                directory = environ['APPDATA'].rstrip("\\") + "\\OpenRGB"
            else:
                directory = '.'
        with open(f'{directory}/{name}.orp', 'rb') as f:
            controllers = utils.LocalProfile.unpack(f).controllers
            pairs = []
            for device in self.devices:
                for new_controller in controllers:
                    if new_controller.name == device.name \
                            and new_controller.device_type == device.type \
                            and new_controller.metadata.description == device.metadata.description:
                        controllers.remove(new_controller)
                        pairs.append((new_controller, device))
            # print("Pairs:")
            for new_controller, device in pairs:
                # print(device.name, new_controller.name)
                if new_controller.colors != device.colors:
                    device.set_colors(new_controller.colors)
```

--------------------------------

### Serialize LEDData class to binary format in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

Packs LEDData objects into binary bytes for OpenRGB SDK transmission. Combines string packing with unsigned int encoding. Handles name serialization and numeric value conversion. Returns compact binary representation suitable for network transmission or profile storage. Supports bidirectional conversion with unpack method.

```python
@dataclass
class LEDData:
    name: str
    value: int

    def pack(self, version: int) -> bytes:
        '''
        Packs itself into a bytes ready to be sent to the SDK or saved in a profile

        :returns: raw data ready to be sent or saved
        '''
        return (
            pack_string(self.name)
            + struct.pack("I", self.value)
        )

    @classmethod
    def unpack(cls, data: Iterator[int], version: int, *args) -> LEDData:
        '''
        Creates a new LEDData object from raw bytes

        :param data: the raw bytes from the SDK
        '''
        name = parse_string(data)
        value = parse_var('I', data)
        return cls(name, value)
```

--------------------------------

### Create RGBColor Objects in Python

Source: https://openrgb-python.readthedocs.io/en/latest/pages/usage

Creates color objects from RGB, HSV, or hexadecimal values for lighting control. Uses openrgb.utils.RGBColor class. Accepts color components as inputs; outputs RGBColor instances. HSV uses 0-360 for hue, 0-100 for saturation/value; hex strings may include optional '#' prefix.

```python
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
```

--------------------------------

### Select Devices by Type or Name in Python

Source: https://openrgb-python.readthedocs.io/en/latest/pages/usage

Retrieves specific devices using type enumeration or name strings for reliable access. Requires openrgb.utils.DeviceType for types and supports exact or case-insensitive name matching. Returns device objects; inexact matching may not be unique if multiple devices match.

```python
from openrgb.utils import DeviceType

mobo = cli.get_devices_by_type(DeviceType.MOTHERBOARD)[0]

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'
```

--------------------------------

### RGBObject Class for Generic RGB Control

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

A parent class for RGB control with generic functions for color setting, clearing, and updating. Includes methods for setting color and clearing LEDs.

```python
class RGBObject:
    '''
    A parent class that includes a few generic functions that use the
    implementation provided by the children.
    '''

    def __repr__(self):
        return f"{type(self).__name__}(name={self.name}, id={self.id})"


    def set_color(self, color: RGBColor, fast: bool = False):
        '''
        Sets the color

        :param color: the color to set
        '''
        pass


    def clear(self):
        '''
        Turns all of the LEDS off
        '''
        self.set_color(RGBColor(0, 0, 0))


    def update(self):
        '''
        Gets the current status from the SDK server, ensuring a correct
        internal state.
        '''
        self.comms.requestDeviceData(self.device_id)
```

--------------------------------

### Pack and unpack ControllerData dataclass for OpenRGB in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

ControllerData aggregates device name, metadata, type, LEDs, zones, modes, colors, and the active mode. Its pack method serializes the full controller state into a byte buffer, while unpack parses raw bytes back into a fully populated dataclass. This facilitates bidirectional communication with the OpenRGB SDK.

```Python
@dataclass
class ControllerData:
    name: str
    metadata: MetaData
    device_type: DeviceType
    leds: list[LEDData]
    zones: list[ZoneData]
    modes: list[ModeData]
    colors: list[RGBColor]
    active_mode: int

    def pack(self, version: int) -> bytes:
        '''
        Packs itself into a bytes ready to be sent to the SDK or saved in a profile

        :returns: raw data ready to be sent or saved
        '''
        buff = (
            struct.pack("i", self.device_type)
            + pack_string(self.name)
            + self.metadata.pack(version)
            + struct.pack("H", len(self.modes))
            + struct.pack("i", self.active_mode)
            + b''.join(mode.pack(version)[struct.calcsize("Ii"):] for mode in self.modes)
            + pack_list(self.zones, version)
            + pack_list(self.leds, version)
            + pack_list(self.colors, version)
        )
        buff = struct.pack("I", len(buff) + struct.calcsize("I")) + buff
        return buff

    @classmethod
    def unpack(cls, raw_data: bytes, version: int, start: int = 0) -> ControllerData:
        '''
        Unpacks the raw bytes received from the SDK into a ControllerData dataclass

        :param data: The raw data from a response to a request for device data
        :returns: A ControllerData dataclass ready to pass into the OpenRGBClient's cal function
        '''
        data = iter(raw_data)
        size = parse_var('I', data)
        try:
            device_type = DeviceType(parse_var('i', data))
        except ValueError:
            device_type = DeviceType.UNKNOWN
        name = parse_string(data)
        metadata = MetaData.unpack(data, version)
        num_modes = parse_var('H', data)
        active_mode = parse_var('i', data)
        modes = []
        for x in range(num_modes):
            mode = ModeData.unpack(data, version, x)
            modes.append(mode)
        zones = parse_list(ZoneData, data, version)
        leds = parse_list(LEDData, data, version)
        colors = parse_list(RGBColor, data, version)
        i = 0
        for zone in zones:
            zone.start_idx = i
            zone.leds = leds[i:i + zone.num_leds]
            zone.colors = colors[i:i + zone.num_leds]
            i += zone.num_leds
        return cls(
            name,
            metadata,
            device_type,
            leds,
            zones,
            modes,
            colors,
            active_mode
        )
```

--------------------------------

### Parsing and Packing Utility Functions for OpenRGB Data (Python)

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/utils

Provides functions for parsing and packing various data types used in the OpenRGB protocol, such as variable-sized integers, strings, and lists of objects. These utilities are essential for serializing data to send to the SDK and deserializing data received from it.

```python
import struct
from typing import Iterator, Any

def parse_var(type: str, data: Iterator[int]) -> Any:
    size = struct.calcsize(type)
    d = []
    for _ in range(size):
        d.append(int(next(data)))
    try:
        return struct.unpack(type, bytes(d))[0]
    except IndexError:
        return

def parse_string(data: Iterator[int]) -> str:
    length = parse_var('H', data)
    return parse_var(f'{length}s', data).decode().rstrip('\x00')

def pack_string(string: str) -> bytes:
    num = len(string)
    return struct.pack(f"H{num}s", num + 1, string.encode('ascii')) + b'\x00'

def parse_list(kind: object, data: Iterator[int], version: int) -> list:
    length = parse_var('H', data)
    things = []
    for x in range(length):
        things.append(kind.unpack(data, version, x))  # type: ignore
    return things

def pack_list(things: list, version: int) -> bytes:
    return bytes(struct.pack("H", len(things))) + b''.join(thing.pack(version) for thing in things)
```

--------------------------------

### Optimize OpenRGB-Python for Speed

Source: https://openrgb-python.readthedocs.io/en/latest/_sources/pages/advanced

This snippet demonstrates how to minimize SDK calls for faster effect rendering. It highlights the use of the 'fast' argument in color-changing functions to skip internal state management.

```python
cli.devices[0].set_color(RGBColor(255, 0, 0))
cli.devices[0].set_color(RGBColor(0, 255, 0), 4, 8)
cli.devices[0].zones[0].set_color(RGBColor(0, 0, 255))
```

```python
cli.devices[0].set_colors([
    RGBColor(0, 0, 255)]*3
    + [RGBColor(255, 0, 0)]
    + [RGBColor(0, 255, 0)]*4
)
```

```python
cli.devices[0].colors = [RGBColor(255, 0, 0)]*8
cli.devices[0].colors[:3] = [RGBColor(0, 0, 255)]*3
cli.devices[0].colors[4:8] = [RGBColor(0, 255, 0)]*4
cli.devices[0].show()
```

--------------------------------

### update()

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Synchronizes device state with the SDK server. Useful when changes are made through GUI or other SDK clients.

```APIDOC
## update()

### Description
Gets the current state of your devices from the SDK server. Useful for syncing changes made from GUI or other SDK clients.

### Method
POST

### Endpoint
/update

### Request Example
```
POST /update
```

### Response
#### Success Response (200)
- **status** (string) - Update completion status

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Plugin Class - OpenRGB Python

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Represents a plugin within the OpenRGB system, storing its name, description, version, ID, and SDK version. Includes methods for packing and unpacking plugin data.

```python
class _openrgb.utils.Plugin(_name_, _description_, _version_, _id_, _sdk_version_):
    Bases: `object`

    description: `str`
    id: `int`
    name: `str`

    def pack():
        pass

    sdk_version: `int`

    @classmethod
    def _unpack(_data_, _version_, *_args_):
        Return type:
            `Plugin`
        pass

    version: `str`
```

--------------------------------

### Set Zone LED Colors in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

This method sets colors for LEDs in a specific zone, ensuring the color list matches the LED count. It uses struct packing to send data over network communication and includes a fast mode option for performance. Dependencies include utils module for packet types and RGBColor. Input is a list of RGBColor objects and a boolean for fast mode; output is sent data or exception if mismatch.

```python
if len(colors) != len(self.leds):
    raise IndexError(
        "Number of colors doesn't match number of LEDs in the zone")
self.comms.send_header(
    self.device_id,
    utils.PacketType.RGBCONTROLLER_UPDATEZONELEDS,
    struct.calcsize(f"iIH{3*(len(self.leds))}b{len(self.leds)}x")
)
buff = struct.pack("iH", self.id, len(self.leds)) + \
    b''.join((color.pack() for color in colors))
buff = struct.pack("I", len(buff) + struct.calcsize("I")) + buff
self.comms.send_data(buff)
if not fast:
    self.update()
```

--------------------------------

### Device Control and Update - Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Updates all devices, optionally forcing color changes. It then calls a general update on the SDK. This method is crucial for applying changes to connected RGB devices.

```python
    def update_all_devices(self, fast: bool = False, force: bool = False):
        '''
        Updates all devices, optionally forcing color changes.

        :param fast: If True, skips the final SDK update.
        :param force: Sets all colors rather than trying to only set the ones that have been changed
        '''
        for dev in self.devices:
            dev.show(True, force)
        if not fast:
            self.update()

```

--------------------------------

### update_profiles()

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Retrieves the list of available profiles from the server.

```APIDOC
## update_profiles()

### Description
Gets the list of available profiles from the server.

### Method
POST

### Endpoint
/update_profiles

### Request Example
```
POST /update_profiles
```

### Response
#### Success Response (200)
- **profiles** (array) - List of available profiles

#### Response Example
{
  "profiles": ["Gaming", "Office", "Movie"]
}
```

--------------------------------

### update_plugins()

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Retrieves the list of currently enabled plugins from the server.

```APIDOC
## update_plugins()

### Description
Fetches the current list of enabled plugins from the server.

### Method
POST

### Endpoint
/update_plugins

### Request Example
```
POST /update_plugins
```

### Response
#### Success Response (200)
- **plugins** (array) - List of enabled plugins

#### Response Example
{
  "plugins": ["Network Plugin", "Serial Plugin"]
}
```

--------------------------------

### OpenRGBClient Properties

Source: https://openrgb-python.readthedocs.io/en/latest/pages/api

Provides access to specific attributes of the OpenRGBClient, such as device lists and protocol version.

```APIDOC
## OpenRGBClient Properties

### `ee_devices`

#### Description
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.

#### Property Type
List of devices

### `protocol_version`

#### Description
The protocol version of the connected SDK server.

#### Property Type
int

```

--------------------------------

### Set Device LED Colors in Python

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

This method sets individual colors for each LED on the device, checking for color count match. It joins packed colors and sends via network, with fast mode option. Dependencies include utils for types and colors. Input is a list of RGBColor and boolean; raises error on mismatch, sends data.

```python
if len(colors) != len(self.leds):
    raise IndexError("Number of colors doesn't match number of LEDs")
self.comms.send_header(
    self.id,
    utils.PacketType.RGBCONTROLLER_UPDATELEDS,
    struct.calcsize(f"IH{3*(len(self.leds))}b{len(self.leds)}x")
)
buff = struct.pack("H", len(self.leds)) + \
    b''.join((color.pack() for color in colors))
buff = struct.pack("I", len(buff) + struct.calcsize("I")) + buff
self.comms.send_data(buff)
if not fast:
    self.update()
```

--------------------------------

### Update OpenRGB devices

Source: https://openrgb-python.readthedocs.io/en/latest/_modules/openrgb/orgb

Synchronizes device state with the OpenRGB SDK server. Updates device data and optionally profiles and plugins based on protocol version.

```python
self.comms.requestDeviceNum()
for x in range(self.device_num):
    self.comms.requestDeviceData(x)
if self.comms._protocol_version >= 2:
    self.update_profiles()
if self.comms._protocol_version >= 4:
    self.update_plugins()
```
Tokens:
Raw