LumenScript API

Introduction

LumenScript is a text-based language designed for controlling LED sequences in embedded systems. The focus is on providing a human-readable syntax that is optimized for simple parsing on resource-constrained microcontrollers, while including essential control flow structures.

General Syntax

• Commands are one per line: COMMAND [arguments...].
• Comments start with #.
• Targets: all, led(N) (1-based), leds(N..M), %group_name.
• Colors: red, green, etc., rgb(R,G,B), #RRGGBB, $variable.
• Brightness: 0-255 integer, keyword brightness.
• Durations: Integer + unit (ms, s), e.g., 500ms, $variable.
• Numbers: Integers or decimals for variables, parameters.
• Blocks: Always enclosed in { ... }. Required for loop, repeat, if/else if/else, func.
• Variables: Global scope, defined with set $name = value, referenced with $name. Basic arithmetic (+, -, *, /) supported for numeric variables.

Commands

---

set

Instantly sets properties or variables.

Syntax:

• set [target] color [color_value]
• set [target] brightness [0-255]
• set [target] color [color_value] brightness [0-255] (Order fixed)
• set $var = [value]
• set $var = $var [op] [numeric_value_or_var] (Arithmetic)

Parameters:

• target: all, led(N), leds(N..M), %group.
• color_value: Name, rgb(), #, or $variable.
• 0-255: Brightness value.
• value: Number, color, duration, or target for variable assignment.
• op: +, -, *, / (Requires numeric operands).

Examples:

set led(1) color red
set led(1) brightness 255
set leds(5..8) color blue brightness 128
set $max_b = 200
set $delay = 500ms
set $counter = 0
set $counter = $counter + 1

---

delay

Pauses execution.

Syntax:

delay [duration]

Example:

delay 1s, delay $my_pause

---

fade

Smoothly transitions properties over time.

Syntax:

fade [target] (color [color_value])? (brightness [0-255])? over [duration]
(Requires at least one of color or brightness. Order fixed if both present)

Parameters:

• target: The LED(s) to affect.
• color_value: (Optional) Target color.
• 0-255: (Optional) Target brightness.
• duration: Transition time (e.g., 500ms, $fade_time).

Examples:

fade all color green brightness 255 over 2s
fade led(3) brightness 50 over 500ms
fade %mygroup color white over 1s

---

flicker (Simplified)

Activates a predefined flicker effect using the LED's current color and brightness as the peak. Parameters are now fixed by the implementation for simplicity. Use stop_effect to cancel.

Syntax:

flicker [target]

Parameters:

• target: The LED(s) to affect.
• (Implementation defines frequency/duty cycle, e.g., 2Hz/50%)

Example:

flicker all
flicker %mygroup

---

stop_effect

Cancels active effects (flicker) on target LEDs.

Syntax:

stop_effect [target]

Example:

stop_effect all

---

define

Defines a named group of LEDs.

Syntax:

define %group_name = [target_definition]

Parameters:

• %group_name: Name (e.g., %front).
• target_definition: led(N), leds(N..M), (target1, target2, ...) (combinations allowed).

Example:

define %front = leds(1..4)
define %odd = (led(1), led(3), led(5))

---

loop

Repeats a block indefinitely. Use break to exit.

Syntax:

loop {
    # commands...
    # use 'break' to exit
    # use 'continue' to skip to next iteration
}

Example:

set $counter = 0
loop {
    # ... do cycle ...
    set $counter = $counter + 1
    if $counter > 10 {
        break # Exit loop after 10 cycles
    }
    delay 100ms
}

---

repeat

Repeats a block a specific number of times.

Syntax:

repeat [N_or_$var] times {
    # commands...
    # use 'break' to exit early
    # use 'continue' to skip to next iteration
}

Parameters:

• N_or_$var: Number of repetitions (integer or $variable).

Example:

repeat 5 times {
    set led(2) color blue
    delay 100ms
    set led(2) color black
    delay 100ms
}

---

if / else if / else

Conditionally executes blocks. {...} are mandatory.

Syntax:

if $[variable] [op] [value_or_$var] {
    # commands if true...
} else if $[variable] [op] [value_or_$var] {
    # commands if first is false and this is true...
} else {
    # commands if all preceding conditions are false...
}

(else if and else are optional)

Parameters:

• variable: Variable name (must hold a numeric value).
• op: ==, !=, >, <, >=, <=.
• value_or_$var: Numeric literal or variable to compare against.

Example:

set $level = 150
if $level > 200 {
    set all color red
} else if $level > 100 {
    set all color yellow
} else {
    set all color green
}

---

func / call (Parameter-less)

Defines and calls simple, reusable command sequences without parameters.

Syntax:

# Definition
func function_name() {
    # commands...
}

# Execution
call function_name()

Example:

func flash_white() {
    set all color white brightness 255
    delay 50ms
    set all brightness 0
    delay 50ms
}

# Use it
call flash_white()
delay 500ms
call flash_white()

---

break

Immediately exits the current loop or repeat block.

Syntax:

break

---

continue

Skips the rest of the current iteration of a loop or repeat block and proceeds to the next iteration (or condition check).

Syntax:

continue

---

Example Script

# Define groups
define %front = leds(1..4)
define %back = leds(5..8)

# Define vars
set $main_color = rgb(0, 80, 200)
set $accent_color = #FFA500
set $fade_time = 1s
set $max_loops = 5
set $loop_count = 0

# Define simple functions
func initial_setup() {
    set all color black brightness 0
    delay 500ms
    fade all color $main_color brightness 200 over $fade_time
    delay $fade_time
}

func fade_out() {
    fade all brightness 0 over 2s
    delay 2s
}

# --- Main Script ---
call initial_setup()

repeat $max_loops times {
    set $loop_count = $loop_count + 1

    # Alternate effect based on loop counter
    if $loop_count == $max_loops {
        # Special last loop action
        fade %front color white over 1s
        fade %back color $accent_color over 1s
        delay 1s
    } else if $loop_count % 2 == 0 { # Even loops (modulo operator needed in impl)
        # Pulse front
        fade %front color $accent_color over 500ms
        delay 500ms
        fade %front color $main_color over 500ms
        delay 500ms
    } else { # Odd loops
        # Flicker back (using simplified command)
        flicker %back
        delay 2s
        stop_effect %back
    }

    # Example using continue (e.g., skip delay on first loop)
    if $loop_count == 1 {
        continue # Skip the final delay
    }

    delay 250ms # Short delay between loops unless skipped
}

# Example using break (though not necessary here as repeat finishes)
# loop {
#   if some_condition { break }
# }

call fade_out()
# --- End Script ---