protocol_description.txt

This file contains the description of the OpenRGB network API (protocol) that this client implements.
The protocol is evolving, the current state of the document describes version 3, but it may change in the future.
It uses a pseudo-language which shall be understood as follows:
 * 'message' means a self-contained block of TCP data that represents a request or a response
 * 'section' means a part of message that is either repeated or part of multiple different messages
 * 'enum' is classical enum like in any programming language
 * 'char[]' is used where the size of the array is dynamic and usually depends on a field that preceeds it
 * 'optional' means the following element might or might not be present depending on some field that preceeds it
 * all integers are in little-endian
 * all messages and sections are "packed" - there are no padding bytes, integer fields might not be alligned to offsets that are multiples of their size
 * all strings comming from the client must be terminated by '\0' character, and the 2-byte length field that preceeds them counts the terminating character too
   however strings comming from the server are often not null-terminated, so read them by using the preceeding length or the packet length


enum MessageType : uint32
{
	REQUEST_CONTROLLER_COUNT       = 0,
	REQUEST_CONTROLLER_DATA        = 1,
	REQUEST_PROTOCOL_VERSION       = 40,
	SET_CLIENT_NAME                = 50,
	DEVICE_LIST_UPDATED            = 100,
	RGBCONTROLLER_RESIZEZONE       = 1000,
	RGBCONTROLLER_UPDATELEDS       = 1050,
	RGBCONTROLLER_UPDATEZONELEDS   = 1051,
	RGBCONTROLLER_UPDATESINGLELED  = 1052,
	RGBCONTROLLER_SETCUSTOMMODE    = 1100,
	RGBCONTROLLER_UPDATEMODE       = 1101,
	RGBCONTROLLER_SAVEMODE         = 1102,
}

// Every protocol message starts with this.
section Header
{
	char[4]     magic = "ORGB";
	uint32      device_idx;
	MessageType message_type;
	uint32      message_size;  // size of message minus size of this header
}

// Type of the device with RGB LEDs
enum DeviceType : uint32
{
	Motherboard   = 0,
	DRAM          = 1,
	GPU           = 2,
	Cooler        = 3,
	LedStrip      = 4,
	Keyboard      = 5,
	Mouse         = 6,
	MouseMat      = 7,
	Headset       = 8,
	HeadsetStand  = 9,
	Gamepad       = 10,
	Light         = 11,
    Speaker       = 12,
    Virtual       = 13,
	Unknown,
}

// Which features the mode supports
enum ModeFlags : uint32
{
	HasSpeed              = (1 << 0),  // the speed attribute in ModeDescription is present
	HasDirectionLR        = (1 << 1),  // the direction attribute in ModeDescription can have Left or Right values
	HasDirectionUD        = (1 << 2),  // the direction attribute in ModeDescription can have Up or Down values
	HasDirectionHV        = (1 << 3),  // the direction attribute in ModeDescription can have Horizontal or Vertical values
	HasBrightness         = (1 << 4),  // the brightness attribute in ModeDescription is present
	HasPerLedColor        = (1 << 5),  // the color_mode attribute in ModeDescription can be set to PerLed
	HasModeSpecificColor  = (1 << 6),  // the color_mode attribute in ModeDescription can be set to ModeSpecific
	HasRandomColor        = (1 << 7),  // the color_mode attribute in ModeDescription can be set to Random
}

// Direction of the color effect
enum Direction : uint32
{
	Left        = 0,
	Right       = 1,
	Up          = 2,
	Down        = 3,
	Horizontal  = 4,
	Vertical    = 5,
}

// How the colors of a mode are set
enum ColorMode : uint32
{
	None          = 0,  // mode has no colors
	PerLed        = 1,  // mode has per LED colors
	ModeSpecific  = 2,  // mode specific colors
	Random        = 3,  // mode has random colors
}

/// Type of RGB zone
enum ZoneType : uint32
{
	Single  = 0,
	Linear  = 1,
	Matrix  = 2,
}

// Asks server how many RGB devices (controllers) there are.
message RequestControllerCount
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_CONTROLLER_COUNT,
		message_size = 0
	};
}

// A reply to RequestControllerCount
message ReplyControllerCount
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_CONTROLLER_COUNT,
		message_size = 4
	};
	uint32   count;
}

// Asks for all information and supported modes about a specific RGB device (controller).
message RequestControllerData
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = REQUEST_CONTROLLER_DATA,
		message_size = 4
	};
	uint32   protocolVersion;
}

// A reply to RequestControllerData
message ReplyControllerData
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = REQUEST_CONTROLLER_DATA,
		message_size = <dynamic>
	};
	uint32   data_size = header.message_size;  // yes, this value is really there twice, no idea why
	DeviceDescription device_desc;
}

// Tells the server in what version of the protocol the client wants to communite in.
message RequestProtocolVersion
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_PROTOCOL_VERSION,
		message_size = 4
	};
	uint32   version;
}

// A reply to RequestProtocolVersion. Contains the maximum version the server supports.
message ReplyProtocolVersion
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_PROTOCOL_VERSION,
		message_size = 4
	};
	uint32   version;
}

// Announces a custom name of the client to the server.
message SetClientName
{
	Header   header = {
		device_idx = 0,
		message_type = SET_CLIENT_NAME,
		message_size = length(name) + 1
	};
	char[]   name;
}

// This is sent from the server everytime its device list has changed.
message DeviceListUpdated
{
	Header   header = {
		device_idx = 0,
		message_type = DEVICE_LIST_UPDATED,
		message_size = 0
	};
}

// Resizes a zone of LEDs, if the device supports it.
message ResizeZone
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = RGBCONTROLLER_RESIZEZONE,
		message_size = 8
	};
	uint32   zone_idx;
	uint32   new_size;
}

// Applies individually selected color to every LED.
message UpdateLEDs
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = RGBCONTROLLER_UPDATELEDS,
		message_size = <dynamic>
	};
	uint32   data_size = header.message_size;  // yes, this value is really there twice, no idea why
	uint16   num_colors;
	Color[]  colors;
}

// Applies individually selected color to every LED in a specific zone.
message UpdateZoneLEDs
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = RGBCONTROLLER_UPDATEZONELEDS,
		message_size = <dynamic>
	};
	uint32   data_size = header.message_size;  // yes, this value is really there twice, no idea why
	uint32   zone_idx;
	uint16   num_colors;
	Color[]  colors;
}

// Changes color of a single particular LED.
message UpdateSingleLED
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = RGBCONTROLLER_UPDATESINGLELED,
		message_size = length(name) + 1
	};
	uint32   led_idx;
	Color    color;
}

// Switches mode of a device to a directly controlled one.
message SetCustomMode
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = RGBCONTROLLER_SETCUSTOMMODE,
		message_size = 0
	};
}

// Switches mode of a device to a directly controlled one.
message UpdateMode
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = RGBCONTROLLER_UPDATEMODE,
		message_size = <dynamic>
	};
	uint32   data_size = header.message_size;  // yes, this value is really there twice, no idea why
	uint32   mode_idx;
	ModeDescription mode_desc;
}

// Saves the mode parameters into the device memory to make it persistent.
message SaveMode
{
	Header   header = {
		device_idx = <selected_device>,
		message_type = RGBCONTROLLER_SAVEMODE,
		message_size = <dynamic>
	};
	uint32   data_size = header.message_size;  // yes, this value is really there twice, no idea why
	uint32   mode_idx;
	ModeDescription mode_desc;
}

// Asks for a list of saved profiles.
message RequestProfileList
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_PROFILE_LIST,
		message_size = 0
	};
};

// A reply to RequestProfileList
message ReplyProfileList
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_PROFILE_LIST,
		message_size = <dynamic>
	};
	uint32   data_size = header.message_size;  // yes, this value is really there twice, no idea why
	uint16   num_profiles;
	ProfileName[] profiles;
};

// Saves the current configuration of all devices under a new profile name.
message RequestSaveProfile
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_SAVE_PROFILE,
		message_size = length(profileName) + 1
	};
	char[]   profileName;
};

/// Applies an existing profile.
message RequestLoadProfile
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_LOAD_PROFILE,
		message_size = length(profileName) + 1
	};
	char[]   profileName;
};

// Removes an existing profile.
message RequestDeleteProfile
{
	Header   header = {
		device_idx = 0,
		message_type = REQUEST_DELETE_PROFILE,
		message_size = length(profileName) + 1
	};
	char[]   profileName;
};

section DeviceDescription
{
	DeviceType type;
	uint16     name_length;
	char[]     name;
	uint16     description_length;
	char[]     description;
	uint16     version_length;
	char[]     version;
	uint16     serial_length;
	char[]     serial;
	uint16     location_length;
	char[]     location;
	uint16     num_modes;
	uint32     active_mode;
	ModeDescription[]  modes;
	uint16     num_zones;
	ZoneDescription[]  zones;
	uint16     num_leds;
	LEDDescription[]   leds;
	uint16     num_colors;
	Color[]    colors;
}

section ModeDescription
{
	uint16    name_length;
	char[]    name;
	uint32    value;           // device-specific value
	uint32    flags;           // see ModeFlags for possible bit flags
	uint32    speed_min;       // minimum speed value, this attribute is valid only if ModeFlags::HasSpeed is set, otherwise it's uninitialized
	uint32    speed_max;       // maximum speed value, this attribute is valid only if ModeFlags::HasSpeed is set, otherwise it's uninitialized
	uint32    brightness_min;  // minimum brightness value, this attribute is valid only if ModeFlags::HasBrightness is set, otherwise it's uninitialized
	uint32    brightness_max;  // maximum brightness value, this attribute is valid only if ModeFlags::HasBrightness is set, otherwise it's uninitialized
	uint32    colors_min;      // minimum number of mode colors
	uint32    colors_max;      // maximum number of mode colors
	uint32    speed;           // speed of the effect, this attribute is valid only if ModeFlags::HasSpeed is set, otherwise it's uninitialized
	uint32    brightness;      // brightness of the lights, this attribute is valid only if ModeFlags::HasBrightness is set, otherwise it's uninitialized
	Direction direction;       // direction of the color effect, this attribute is only valid if any of ModeFlags::HasDirectionXY is set, otherwise it's uninitialized
	ColorMode color_mode;      // how the colors of a mode are set
	uint16    num_colors;
	Color[]   colors;          // mode-specific list of colors
}

section ZoneDescription
{
	uint16   name_length;
	char[]   name;
	ZoneType type;
	uint32   leds_min;    // minimum size of the zone
	uint32   leds_max;    // maximum size of the zone
	uint32   leds_count;  // current size of the zone
	uint16   matrix_length = <size of the optional block>
	optional (if matrix_length > 0) {
		uint32   matrix_height;
		uint32   matrix_width;
		uint32[] matrix_values;
	}
}

section LEDDescription
{
	uint16   name_length;
	char[]   name;
	uint32   value;  // device-specific value
}

section ProfileName
{
	uint16   name_length;
	char[]   name;
}

section Color
{
	uint8  red;
	uint8  green;
	uint8  blue;
	uint8  padding = 0;
}