This post will show sample scripts from very simple to fairly complicated. I’ll explain the most useful elements and attributes of wiLED JSON.
The simples script sets all LEDs to the same color:
{
"elements": [ {"hue": 120} ]
}
Every script has an array of elements. In this example, there is a single element which sets every LED to hue 120, which is green. The system infers the type, and adds some default attributes. A more verbose version of the same script is
{
"elements": [
{
"type": "hsl",
"hue": 120,
"saturation": 100,
"lightness": 50,
"offset": 0,
"length": "100%"
}
]
}
The type of this element is “hsl”. It can specify the hue, saturation, and lightness of LEDs. If a script does not specify saturation for an LED, it is set to 100. If lightness is not specified, it is set to 50. These defaults are not set until all elements have been drawn without setting values. You can experiment with different HSL values here .
Almost every wiLED element has a position. The default is an offset of 0, and a length equal to the full length of the parent. Offset and length can be a JSON number, or a string that includes a unit.
A small change to the previous script displays a rainbow across the entire strip:
{
"elements": [
{
"hue": [0,359]
}
]
}
Maybe weird. But very powerful. “[0,359]” is a range value. It’s a shorthand for
{
"elements": [
{
"hue": {"range":[0,359]}
}
]
}
The hue changes from 0 to 359 as the position moves from the first LED in the element to the last.
A range can have a duration attribute which causes it to change over time instead of over position
{
"elements": [
{
"hue": {"range":[0,359], "duration": "5s"}
}
]
}
In this example, all LEDs will be 0 at the start. Over 5 seconds the hue for all LEDS will increment in equal steps so that they are all 359 at the end.
Ranges can be used anywhere a number is allowed. This creates a moving rainbow pattern
{
"elements": [
{
"rhue": [0,359],
"offset": {"range":[0,"100%"], "duration": 10000}
}
]
}
Hue ranges over position, drawing a rainbow. The rainbow starts at the offset position which ranges over time from the first LED of the parent to the last. By default, elements wrap, so when the position gets to the end of the strip it continues at the start.
The elements array can contain multiple elements. This script has 3 elements and a number of new attributes
{
"duration": 1000,
"gap": "3px",
"elements": [
{
"hue": 50,
"length": "5in"
},
{
"green": 255,
"blue": 100,
"length": "15cm"
},
{
"hue": "sys(purple)"
}
]
}
The first thing to point out is the 3 elements flow. The second one continues from the end of the first. And the 3rd from the end of the second. The last element doesn’t have a length, so it flows to the end of it’s parent and in this case fills the strip.
The parent has a “gap” attribute, which is the distance between elements. If gap is not set, it is 0 (no gap).
The first element has a gap of “5in” which is 15 inches. The second element has a length of 15 centimeters. A “pixels/meter” configuration value is used to calculate the number of LEDs in and inch and centimeter. [there is an API for uploading/changing the configuration].
The 2nd element uses RGB instead of HSL. An RGB element sets the Red, Green, and Blue values of pixels. In this case Green and Blue are set and Red defaults to 0. Red, green, and blue values must be set in the same element. Unlike HSL elements where each component may be set in the same element, or in different overlapping elements,
A final point in this example is that the hue in the 3rd element is a named color “sys(purple)”. “sys()” is the way to reference a system variable. And “purple” is the hue for the color purple (I picked 315 as the hue value for purple).
Container elements contain lists of child elements. Containers are positioned like HSL and RGB elements – they have offset, length, and can flow. They contain an “elements” attribute just like a Script (Script JSON is a container). Containers are recursive, and can go as deep as memory allows.
{
"duration": 100000,
"op": "add",
"elements": [
{
"type": "values",
"msecs": 1500
},
{
"offset": {
"range": [
"0%",
"100%"
],
"duration": [
"*",
"var(msecs)",
8
]
},
"elements": [
{
"hue": 50,
"length": "2px"
},
{
"green": 255,
"length": "3px"
}
]
},
{
"offset": {
"range": [
"100%",
"0%"
],
"duration": [
"+",
"var(msecs)",
5000,
3000
]
},
"unit": "pixel",
"elements": [
{
"hue": 0,
"length": "5px"
},
{
"hue": 300,
"length": 8
}
]
},
{
"length": {
"range": [
"40px",
"60px"
],
"duration": "var(msecs)"
},
"offset": "35%",
"unit": "pixel",
"flow": false,
"elements": [
{
"hue": 50,
"length": "10%"
},
{
"hue": 255,
"length": "20%"
}
]
}
]
}
This script may not be useful, but it shows a few new features. First, the top-level container (the script) contains 3 child containers which each contain 2 HSL elements. One child container moves left, another moves right, and the thirds sits in the middle.
The script also has a values element which defines the variable named “msec”. Variables are used with a JSON string “var(NAME)”, so “var(msec)” is the same as 1500 in this script.
The first duration uses the variable in a function. Functions are defined as a JSON array with the first element being the function name. In this case the function name is “*” (“mult” or “multiply” could be used instead”). This multiplies the “msec” variable value of 1500 by 8.
The script also uses the HSL operation “add” (“op”: “add”). The op attribute can be set on any element and it is inherited by child elements unless they set their own value. “add” cause hue, saturation, and lightness values to be added when 2 HSL elements overlap. The default is “replace” which replaces earlier values with the last HSL element drawn to an LED. Other operations are “subtract”, “average”, “min”, and “max”.