Config docs prototype

Disclaimer

This page describes functionality that has not yet been implemented, and the specifications below onl act as a proposal. The specification below may not follow the existing implementation of the same features, can be changed or removed at any point, and may never be implemented as described.

This page will be moved to Wiki when the config implementation gets pulled into mainline branch. Please leave your suggestions to the given structure.

Abstract

This page describes the structure of the OpenRGB.json configuration file. Any of the fields described below may be omitted if the default value fits the purpose, unless the field name is marked in bold, however, some values will be placed in the file automatically to help guide the user.

On Linux, both files will be located in $XDG_CONFIG_HOME/OpenRGB, typically ~/.config/OpenRGB/. If the $XDG_CONFIG_HOME variable is unavailable, $HOME/.config/OpenRGB would be used instead, effectively producing the same path. On Windows, the config files will be located in a folder inside the user's AppData folder, the application folder name will be "OpenRGB". If a --config option is specified, an alternative configuration file will be used, and all paths will be derived from the location of that file, unless specified otherwise. CLI option is not implemented.

Proposing that top-level objects be named "Setting_X" where X is the object name below. This could change.

Values to be stored in OpenRGB.json:

General Settings

  • Detectors object
    • disable_i2c: a boolean value that turns off the I2C subsystem of OpenRGB completely. All detection will be skipped, all I2C-related tools will be disabled.
    • detectors: a list of string:boolean pairs denoting each detector's enabled state. Set the boolean to false to disable a given detector.
    • controllers: an object (map), containing objects associated by name to a specific device class. Most fields have the same meaning as in devices.json, however, not all values from there apply here. Device-specific values override global ones. The list of controllers is updated automatically to contain all the controllers available to the application, so the user doesn't have to look up specific names. If the controller doesn't require any settings, it can be replaced by a single boolean value that will be used as enabled flag.
      • enabled: whether this controller is used by application or not; this is the field primarily used to disable specific controllers.
      • zones: for controller types with resizable zones, this field can contain the initial sizes for those zones; note that device-specific configuration overrides this value and setting this field does NOT mark devices of this type as "calibrated". Can be removed.
      • theme: an object or a string; see description for devices.json.
      • any controller-specific configuration that must be applied to ALL devices of this class; calibration values can not be assigned through this field. see description for devices.json for details.
  • SDK object
    • disable_sdk: a boolean value that turns off the SDK and all SDK-related features completely. All GUI tabs, tools and connections will be disabled.
  • client object
    • logfile: path to a log file. Defaults to a randomly-generated filename with a fixed prefix either in the local app directory or in the temp directory. May contain a tag to be replaced with current timestamp.
    • loglevel: an object containing integer numbers associated with different modules of the app, declaring how many log entries it may produce. If a value for certain module is not specified, the value of "default" field used instead. The loglevel field can also be a single integer which would be used for all modules.
    • servers: an array, containing the list of servers the client connects to as objects with fields address, port, name and auto_connect. The client will attempt to connect to a localhost server on a default port even if it is not listed here.
    • device_view_shown: a boolean value; whether the device view should be shown on application startup or not.
    • dark_mode: Windows only: whether the app should use dark theme or not; can be a boolean or a string with values "On", "Off", "Auto". Default is "Auto", which means the app follows the system-wide setting. On non-windows platforms, the theme and color scheme are defined system-wide.

Device-Specific Settings

  • DebugDevices object
    • devices: array of parameter:value pairs:
      • type: String, one of argb, dram, gpu, motherboard, or keyboard
  • E131Devices object
    • devices: array of parameter:value pairs:
      • name: String, name of E1.31 device
      • num_leds: Number, number of LEDs on device
      • start_universe: Number, starting E1.31 universe
      • start_channel: Number, starting E1.31 channel
      • type: String, one of SINGLE, LINEAR, or MATRIX
  • EspurnaDevices object
    • devices: array of parameter:value pairs:
      • apikey: String, API key for Espurna API
      • ip: String, IP address
      • port: String, port number
  • LEDStripDevices object
    • devices: array of parameter:value pairs:
      • baud: Number, serial port baud rate
      • num_leds: Number, number of LEDs on device
      • port: String, serial port name/path
  • PhilipsHueBridges object
    • bridges: array of parameter:value pairs:
      • clientkey: String, client key for Entertainment Mode (saved when first paired)
      • ip: String, IP address of bridge
      • mac: String, MAC address of bridge
      • username: String, username from bridge (saved when first paired)
  • PhilipsWizDevices object
    • devices: array of parameter:value pairs:
      • ip: String, IP address

Previously connected devices

section Devices is an array of per-device objects. Each device contains the following fields:

  • name: a string containing the name of the controller object, probably without a numerical suffix. Can also be the name given to a device by the user.
  • location: a string containing the protocol-specific or controller-specific location for this device. For some devices this is the defining field in assigning the config entry to a controller object when more than one controller of the same type is present (RAM), for others it has to be ignored because it changes between the application starts (USB devices).
  • profiles: an array of objects describing different profiles available for this device.
    • name: the name of the profile
    • mode: an object describing mode settings:
      • index
      • direction
      • speed
      • color_mode
      • colors (not to be confused with the colors object une layer above)
    • colors: an array of integers treated as RGBColors, if the mode supports per-led values
  • default_profile: a string containing the name of a profile to be automatically applied to the device when the application is started.
  • calibrated: a boolean value that is set to true after the device is calibrated; only added to the controllers that require calibration.
  • zones: an array that describes led layout for resizable zones; can be empty if the device has no resizable zones, and the zone objects can also be empty if the corresponding zones are non-resizable.
    • name: informational; for user's reference only. A string containing thr name of this zone.
    • subzones: an array of objects, describing subzones of each zone. A subzone is a part of a resizable zone that corresponds to an individual device connected to an ARGB header. In most scenarios ARGB headers will only have one devices connected to them and thus each ARGB header zone will only have one subzone, describing that device.
    • size: an unsigned integer value, should only be present if the subzones field is missing, ignored otherwise. Describes the size assigned to this device if subzones can not be described.
  • invert_colors: a special field for rare devices which require some alteration to the color representation; description form is to be discussed later (either a boolean or a string of a specific format). If a device requires an inversion calibration, but this field is missing, the calibrated field is forcibly set to false. Note that it may be added automatically even to an uncalibrated device and thus can not be used as a marker of a calibrated device.
  • last_connected: timestamp denoting the last time this device was detected. May be updated during the application runtime (on rescans, some network requests, controller destruction or application shutdown or for other reasons), but is NOT to be updated every second to avoid damage to SSDs.
  • group: an optional field only present on devices added to a group controller. This value must be the same as the controller's name. If a group controller with this name is not found, this field is automatically removed and the device will be displayed at global scope instead.

Any fields that do not fit the given structure will be ignored. They do not count as errors in order to provide a way to extend the structure in the future versions, thus these fields should be preserved in the file when it is being changed.

Edited by Dmitry K