1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

hyperion-remote JSON interface

Introduction

Hyperion comes with a simple command line utility, _hyperion-remote_, to send command to the Hyperion server using the Json interface.

Setting the leds

The leds can be set using the color or image command. The color command will set all leds to the same color and the image command will read an image file and set all leds according to this image. Both commands can optionally be given a priority and/or a duration. When no duration is given, a clear command is needed to switch the leds off again.
Clearing the leds
A priority channel can be cleared using the two clear command: clear and clearall. Clear will only clear the priority channel provided by the priority parameter or use the default when the parameter is not provided. Clearall on the other hand will clear all active priority channels and effectively set all leds to black.

Color transformations

Color transformation can be applied to adjust the values written to the led device. The following transformations are supported (All transformations are executed in the order of the list below):
  • HSL color transform
  • Saturation: apply gain factor
  • luminance: apply gain factor
  • setting up the whitelvl
  • Transform for each color component (red, green, and blue)
  • Threshold: all values below the threshold will be zeroed
  • Gamma: apply a gamma curve

Note: changes to the color transformations are not written to the configuration file of Hyperion at this moment. Any changes made to the color transformations using the Json interface will be lost after a restart of Hyperion. Nevertheless, setting the color transformations using the command line utility provides an easy and fast way to find a good configuration.

Json interface

The Json interface provided by the server is a simple text base interface where messages are newline separated. The format of each message can simply be seen by running the _hyperion-remote_ with the --print options to display the messages which are exchanged between the client and the server.

Usage

Code:
Shell
Simple application to send a command to hyperion using the Json interface
hyperion-remote:
        version   : <version> (brindosch-ef901d5/f330c1b-1459553048
        build time: <build time>

Parameters:
--print                      Print the json input and output messages on stdout
-h, --help                  Show this help message and exit
-a, --address <arg>   Set the address of the hyperion server [default: localhost:19444]
-p, --priority <arg>     Use to the provided priority channel (the lower the number, the higher the priority) [default: 100]
-d, --duration <arg>    Specify how long the leds should be switched on in millseconds [default: infinity]
-c, --color <arg>        Set all leds to a constant color (either RRGGBB hex value or a color name. The color may be repeated multiple time like: RRGGBBRRGGBB)
-i, --image <arg>        Set the leds to the colors according to the given image file
-e, --effect <arg>       Enable the effect with the given name
     --effectArgs <arg> Arguments to use in combination with the specified effect. Should be a Json object string.
-l, --list                      List server info and current active effect with priority and duration
-x, --clear                   Clear data for the priority channel provided by the -p option
     --clearall               Clear data for all active priority channels or one or more of the available color modding operations:
-q, --qualifier               Set the Identifier(qualifier) of the transform to set
-s, --saturation <arg>  !DEPRECATED! Will be removed! Set the HSV saturation gain of the leds
-v, --value <arg>         !DEPRECATED! Will be removed! Set the HSV value gain of the leds
-u, --saturationL <arg> Set the HSL saturation gain of the leds
-m, --luminance <arg> Set the HSL luminance gain of the leds
-n, --luminanceMin <arg>    Set the HSL luminance minimum of the leds (backlight)
-g, --gamma <arg>      Set the gamma of the leds (requires 3 space seperated values)
-t, --threshold <arg>    Set the threshold of the leds (requires 3 space seperated values between 0.0 and 1.0)
-b, --blacklevel <arg>  !DEPRECATED! Will be removed! Set the blacklevel of the leds (requires 3 space seperated values which are normally between 0.0 and 1.0)
-w, --whitelevel <arg> !DEPRECATED! Will be removed! Set the whitelevel of the leds (requires 3 space seperated values which are normally between 0.0 and 1.0)
-y, --qualifier               !DEPRECATED! Will be removed! Set the Identifier(qualifier) of the correction to set
-Y, --correction <arg>  !DEPRECATED! Will be removed! Set the color correction of the leds (requires 3 space seperated values which are normally between 0 and 255)
-z, --qualifier               Set the Identifier(qualifier) of the temperature to set
-Z, --temperature <arg>Set the color temperature of the leds (requires 3 space seperated values which are normally between 0 and 255)
-j, --qualifier                Set the Identifier(qualifier) of the adjustment to set
-R  --redAdjustment <arg>    Set the adjustment of the red color (requires 3 space seperated values between 0 and 255)
-G  --greenAdjustment <arg>  Set the adjustment of the green color (requires 3 space seperated values between 0 and 255)
-B  --blueAdjustment <arg>   Set the adjustment of the blue color (requires 3 space seperated values between 0 and 255)
Effect arguments

Some effects can be customized by adding the --effectArgs parameter. To find out if and how an effect can be customized open the .json files in /usr/share/hyperion/effects/ and look for the "args" section. For example the .json file for the Knight Rider effect looks like this:
Code:
{
    "name" : "Knight rider",
    "script" : "knight-rider.py",
    "args" :
    {
        "speed" : 1.0,
        "fadeFactor" : 0.7,
        "color" : [255,0,0]
    }
}[/SIZE]
In order to start the effect in green instead of red you would use the following command:
Code:
hyperion-remote --effect 'Knight rider' --effectArgs '{ "speed" : 1.0, "fadeFactor" : 0.7, "color" : [0,255,0] }'
The --effectArgs string must be in valid json form. If you get errors you can validate your string with an online json validator.
Tags:

This page has been seen 9,344 times.