Package: asteria-openrgb
Asteria - a simpleOpenRGBdriverOpenRGB is a great tool for controlling your LEDs, but if you want something more than a static pattern, you'll probably
outgrow its GUI relatively quickly. Fortunately, OpenRGB also offers an SDK that allows programmatic access to your
LEDs.Asteria is a framework to faciliate automatically updating your LEDs (via OpenRGB) in response to various
conditions.To make that more concrete, let's look at an example.Visual ExampleMy current PC case is a be quiet! Pure Base 500DX, which features a nice big LED strip down the front. I configured
Asteria to show the following information on those LEDs:GPU temperature (blue = cold, red = hot)CPU temperature (blue = cold, red = hot)Memory usage (all lights off = 0%, all lights on = 100%)Here's what that looks like all together (…in pitch dark to show off the LEDs, not because I live in the
sewers…):Asteria automatically scales the configured instruments to fit the available LEDs, and periodically updates them (every
500ms by default). Of course, this is only scratching the surface of what's possible—what will you come up with?InstallationAvailable on PyPI asasteria-openrgb(i.e.pip install asteria-openrgb).UsageInvoke the main Asteria driver withasteria CONFIG_FILE. Add--helpfor further options.For an (overly long-winded) tutorial on how to run Asteria via systemd, seethis blog
post.ConceptsHere are the key concepts in Astoria:TheDriveris the core Asteria application loop. It's responsible for polling the configuredInstruments to get
their desired LED outputs, and making the OpenRGB SDK calls to set them accordingly.Note:generally, users should
not need to interact with this directly.Instruments tell the driver how they would like their LEDs illuminated. As part of doing so, they might check the
value of someMetric(e.g., the current CPU temperature), but they aren't required to do so.Metrics represent any variable of interest (e.g., the current CPU temperature, or % of memory used).Scales map aMetricto a convenient range forInstruments to work with.Finally, two OpenRGB terms: a "device" is anything with addressable LEDs. Every device has one or more "zones," which
are regions of independently-addressable LEDs. You can explore your devices and their zones using the OpenRGB GUI;
you'll need the device/zone names to write an Asteriaconfig file.To see how these all fit together, have a look at theconfiguration example.Configuration(This section uses terminology explained in theConcepts section)An Asteria configuration file is aTOMLfile. At the top level, it should contain an array of
tables, where each header starts with two parts: 1) the OpenRGB device and 2) zone (within that device) to which this instrument should be applied.
Note that it is perfectly valid to assign multiple instruments to a single zone; Asteria will fill all available LEDs,
and assign a (roughly) equal quantity to each instrument.There are three possible subsections for each config entry. They are described below.instrumentThis section is always required.Required keystype(string): the name of the Instrument class to use (seeinstruments.py).Optional keysargs(table): other arguments to be passed to the__init__of your instrument. (Note: Asteria will take care of passing
the correspondingmetricfor this instrument—if any—to the__init__call; you do not need to do so.)metricThis section is only required if the correspondinginstrumentrequires a metric.Required keystype(string): the name of the metric function to use (seemetrics.py).Optional keysargs(table): other arguments to be passed to the metric function. (Note: Asteria willpartially
applythe metric function with these arguments, and pass the
resulting zero-argument function to your instrument (after also applying the scale, if any).)scaleThis section is always optional, but providing a scale without a corresponding metric is not permitted.Required keystype(string): the name of the scale function to use (seescales.py).Optional keysargs(table): other arguments to be passed to the scale function.ExampleConsider the CPU temperature example from earlier: we want our LEDs to be blue when the CPU is cool, and red when it
heats up.  Clearly ourmetricof interest is the CPU temperature. Looking in theinstrumentsmodule, we see thatLinearHueRangeoffers the lighting effect we're interested in (gradually switching from one colour to another).
There's just one problem: when we read our CPU temperature, we'll probably get a value like42(degrees Celsius), butLinearHueRangeexpects a value in the range [0, 1]. Fortunately,scales.linearhandles that type of
conversion—we'll just need to tell it what our low and high temperatures thresholds are. Here's what that would
look like in a config file:# An Asteria config is a TOML array of tables. It defines a mapping like this:## {OpenRGB device: {OpenRGB zone: [Asteria instrument(s), ...]}}## where each Asteria instrument can optionally have a metric, and that metric# can optionally have a scale.## Said in words: you have one or more OpenRGB devices (if not, Asteria won't do# much...). Each device has one or more OpenRGB zones. Zero or more Asteria# instruments can be displayed in each zone.# We begin by starting our array of tables. Under this header, we'll be adding# Asteria instruments to be displayed on device "MSI PRO B550M", in zone# "JRAINBOW1".[["MSI PRO B550M-VC WIFI (MS-7C95)"."JRAINBOW1"]]# Here's our first instrument...["MSI PRO B550M-VC WIFI (MS-7C95)"."JRAINBOW1".instrument]type="LinearHueRange"# That's hue as in "HSV hue"args={lower_hue=180,upper_hue=360}# ...which needs a metric...["MSI PRO B550M-VC WIFI (MS-7C95)"."JRAINBOW1".metric]type="get_sensor"# Path to my CPU temperature--see metrics.get_sensor for detailsargs={keys=["k10temp-pci-00c3","Tctl","temp1_input"]}# ...and also a scale.["MSI PRO B550M-VC WIFI (MS-7C95)"."JRAINBOW1".scale]type="linear"# i.e., map a value <= 40 to 0, >= 100 to 1, and use# linear interpolation between the two endpointsargs={lower=40,upper=100}# We add another instrument by adding another entry to the array.# Asteria will divide the LEDs between your effects as evenly as possible.[["MSI PRO B550M-VC WIFI (MS-7C95)"."JRAINBOW1"]]# Here's an instrument that doesn't use a metric or a scale; it just displays a# static colour.["MSI PRO B550M-VC WIFI (MS-7C95)"."JRAINBOW1".instrument]type="StaticColour"args={hex_colour="#FF00FF"}# So, overall: with this config, Asteria will set the top half of the LEDs to# match my CPU temperature, and the bottom half will stay a solid hot pink.