ScratchLink LEDs are WS2811, 5Volt, individually addressable, full color RGB LEDs.
ScratchLink can have a total of 6 separate LED devices with a combined total of 300 individual leds (pixels).
LED Addressing
Devices, such as LED Rings may have multiple pixels (individual LEDs) i.e. a common LED Ring has 16 x LEDs. So, the Device is the LED Ring with 16 pixels being individual LEDs on that Device.
LED Addressing Syntax: “[ ]” means optional argument and “|” means OR
led[Device] [[color] colorValue] [pixel1 pixel2..pixeln|pixel_start-pixel_end][bright value];
Default No Argument Case: All devices and pixels.
Example 1: address all led devices and make all pixels red at default brightness
led red;
Example 2: address led device 0 only and make all pixels red at default brightness
led0 red;
Led pixels (individual leds on an led device) are addressed either as a contiguous range or non-contiguous individual pixels or a combination of both.
Contiguous range: use “pixel_start-pixel_end” i.e. hyphen between pixel start and end.
Example 3: turn on led pixels 5 to 16 as a contiguous series to blue at half bright i.e. 12 pixels in a row.
led blue 5-16 bright 50;
Individual pixels: space separated values, i.e. 3 5 7″
Example 4: turn on led pixels 5 and 16 only to blue at half bright i.e. two pixels only.
led blue 5 16 bright 50;
LED config
LED Configuration Commands: LED strips and rings come in many sizes so each LED device needs to be configured so ScratchLink knows how many individual LEDs (pixels) are present and which esp32 GPIO pin each LED device is connected to.
[pins]: refers to physical input/output pins of the ScratchLink Controller that the LED device is plugged into, being the esp32 GPIO pin number. ScratchLink can have a maximum of 6 LED devices.
[pixels]: refers to the individual LED along that LED strip or ring i.e. pixel 2 means the 2nd led along that LED strip.
Command Syntax: “[ ]” means optional argument and “|” means OR
led config save;
Purpose: saves the led config settings to memory on the ScratchLink Controller which remains until changed.
led config default;
Purpose: loads the stored default LED config from memory on the ScratchLink Controller..
led config info;
Purpose: Reports current LED configuration. Example report below indicates
{LED_Strip:0,Enabled:1,Pin:15,Count:16}
ledDevice config set pinValue countValue GRB|RGB;
Purpose: Sets LED device to esp32 GPIO pin and defines how many pixels (individual LEDs) and if order is GRB or RGB.
Example: Set LED device 0 to esp32 GPIO pin 15 and define it as a 16 x LED pixel strip.
led0 config set 15 16 GRB; ledDevice config size countValue;
Purpose: Defines how many pixels (individual LEDs) on LED device.
Example: Set LED device 0 to a 16 x LED pixel strip.
led0 config size 16; ledDevice config enable [yes|no];
Purpose: Enable/disable config for LED device.
ledDevice config remove;
Purpose: Remove config for LED device.
LED
Command Syntax: “[ ]” means optional argument and “|” means OR
led[Device];
Purpose: Turns specified led device OFF, with a white flash.
Example 1: all pixels OFF on all led devices with a white flash.
led;
Example 2: all pixels OFF on led device 1, with a white flash.
led1;
LED demo
Command Syntax:
led[Device] demo;
Purpose: Demonstrates color display on specified LED device.
Example 1: Demo on LED 3.
led3 demo;
Example 2: Demo on all LEDs.
led demo;
LED flash
Command Syntax:
led[Device] [flash];
Purpose: Quick flash of all LEDs with colour white at 100% brightness
Both [Device] and [flash] are optional which means that “led;” will flash all configured led devices.
Example 1: Flash LED device 2.
led2 flash;
led2;
Example 2: Flash all LED devices.
led flash;
led;
LED color
Command Syntax: “[ ]” means optional argument and “|” means OR
led[Device] [[color] colorValue] [pixel1...pixeln|pixel_start-pixel_end][bright value];
Purpose: Set color of Individual pixels i.e non-contiguous pixels OR a contiguous range (series of led pixels next to each other) or a combination of both.
Defaults: ie. when no arguments provided.
Default colorValue is white.
Default brightValue is 100 or “bright”
Default device is all attached led devices.
Note 1: “color” is also optional i.e. the “colorValue” can be specified without being preceded by “color”- so both the following are correct:
led0 color red;
led0 red;
Note 2: led pixels can also be turned off with the led color command by using the colorValue “black”.
Example 1: Turn on all pixels green then pixels 10-16 off.
led green bright 100;
led black 10-16;
brightValue: either 0 to 100 or off | soft | warm | bright
colorValue: words, hex or RGB as defined below.
Preset Colors as Words: black*, white, red, green, blue, yellow, cyan, magenta, silver, grey, maroon, olive, purple, teal, navy, slateblue.
*black will cause the led to not illuminate i.e. turn off.
Color Hex string format: Use an online hex color picker to generate your hex string for the color you want. https://htmlcolorcodes.com/color-picker/
Color RGB format: Red, Green, Blue format expressed in decimal i.e. each RGB needs to be 0 to 100 not 0 to 255.
Example 2: All pixels to Red on all Led devices at 50% brightness using words or rgb or hex:
led red bright 50;
led (100,0,0) bright 50;
led #FF0000 bright 50;
Example 3: First, third and tenth pixel on LED Device 1 to green at full brightness
led1 green 1 3 10 bright 100;
Example 4: All LED devices and pixels to magenta color entered as decimal RGB values (0 to 100 not 0 to 255) at 1/4 brightness.
led (100,0,100) bright 25;
Example 5: All LED pixels to magenta color entered as a hex string.
led color #FF00FF;
led #FF00FF;
Example 5: LED Device 2, all pixels warm red except 4,5,6 which are bright blue.
led2 red bright warm;
led2 blue 4-6 bright bright;
LED percent
Command Syntax:
led[Device] percent value;
Purpose: Proportionately adjust the current luminosity of all led pixels, on the specified device, by the specified value as a percentage.
Notes: percent value can be any whole number, however, the maximum brightness is capped at the maximum physical luminosity for the leds.
Beware that this “led percent” command does not set the absolute luminosity or brightness as does the “bright” argument in the “led color” command. But rather it adjusts the current brightness by the percentage value down to off or up to maximum brightness.
Example 1: halve the current led luminosity of all pixels on all led devices i.e. 50% brightness of current luminosity.
led percent 50;
Example 2: Double the current pixel brightness on led device 1 i.e. 200%.
led1 percent 200;
Note: If the current led brightness was set at 100 i.e. maximum, then “led1 percent 200” will have no effect as leds are already at maximum brightness. However, if original led brightness was set at 20 then the “led1 bright 200” will double that luminosity to 40.
The “bright” command is absolute luminosity while “percent” is a percentage adjustment of the currently set brightness.
LED off
Command Syntax: “[ ]” means optional argument and “|” means OR
led[Device] off [pixel_start-pixel_end];
Purpose: turn off specified pixels or entire led device.
Default: All LED devices and pixels off.
Note that the command “led black;” will also cause the led to turn off as black is no light.
Example 1: Turn off LED ring 0.
led0 off;
Example 2: Turn off pixel range 3-10 on all LED devices.
led off 3-10;
Note: led pixels can also be turned off with the led color command by using the color value “black”.
Example 3: Turn on all pixels green then pixels 10-16 off.
led green bright 100;
led black 10-16;
Example 4: Turn all leds off using the color command rather than the led off command.
led black;
LED shift
Command Syntax: “[ ]” means optional argument and “|” means OR
led[Device] shift [up|down] [count] [on|off];
Purpose: shift all the pixels up or down, by count amount, with either wrap around on or off
Default: shifts all leds up one with wrap on.
led shift;
Example 1: shift all leds down 1 pixel.
led shift down;
Example 2: shift all leds down 3 pixels.
led shift down 3;
Example 3: shift all leds up 5 pixels with wrap off i.e. pixels at end, when shifted, will be lost not wrapped to the other end.
led shift up 5 off;
Analog Commands
Analog sensors produce a voltage which is measured by an Analog to digital converter on the Controller.
Zero Volts becomes digital 0 while 3.3 Volts becomes 1024.