Tasmota/lib/libesp32/berry_animation/docs/QUICK_START.md

Quick Start Guide

Get up and running with the Berry Animation Framework in 5 minutes using the DSL!

Prerequisites

• Tasmota device with Berry support
• Addressable LED strip (WS2812, SK6812, etc.)

Step 1: Your First Animation

Create a simple pulsing red light:

# Define colors
color red = #FF0000

# Create pulsing animation
animation pulse_red = pulsating_animation(color=red, period=3s)

# Run it
run pulse_red

Step 2: Color Cycling

Create smooth color transitions:

# Use predefined rainbow palette
animation rainbow_cycle = rich_palette(
  palette=PALETTE_RAINBOW,
  cycle_period=5s,
  transition_type=1
)

run rainbow_cycle

Step 3: Custom Palettes

Create your own color palettes:

# Define a sunset palette
palette sunset = [
  (0, #191970),    # Midnight blue
  (64, purple),    # Purple
  (128, #FF69B4),  # Hot pink
  (192, orange),   # Orange
  (255, yellow)    # Yellow
]

# Create palette animation
animation sunset_glow = rich_palette(
  palette=sunset,
  cycle_period=8s,
  transition_type=1
)

run sunset_glow

Step 4: Sequences

Create complex shows with sequences:

animation red_pulse = pulsating_animation(color=red, period=2s)
animation green_pulse = pulsating_animation(color=green, period=2s)
animation blue_pulse = pulsating_animation(color=blue, period=2s)

sequence rgb_show {
  play red_pulse for 3s
  wait 500ms
  play green_pulse for 3s
  wait 500ms
  play blue_pulse for 3s
  
  repeat 2 times:
    play red_pulse for 1s
    play green_pulse for 1s
    play blue_pulse for 1s
}

run rgb_show

Step 5: Dynamic Effects

Add movement and variation to your animations:

# Breathing effect with smooth oscillation
animation breathing = pulsating_animation(
  color=blue,
  min_brightness=50,
  max_brightness=255,
  period=4s
)

# Moving comet effect
animation comet = comet_animation(
  color=white,
  tail_length=8,
  speed=2000
)

# Sparkle effect
animation sparkles = sparkle_animation(
  color=white,
  density=80,
  fade_speed=60
)

run breathing

Common Patterns

Fire Effect

animation fire = rich_palette(
  palette=PALETTE_FIRE,
  cycle_period=2s,
  transition_type=1
)

run fire

Ocean Waves

animation ocean = rich_palette(
  palette=PALETTE_OCEAN,
  cycle_period=6s,
  transition_type=1
)

run ocean

Tips for Success

1. Start Simple - Begin with solid colors and basic effects
2. Use Predefined Palettes - Try PALETTE_RAINBOW, PALETTE_FIRE, PALETTE_OCEAN
3. Test Incrementally - Add one animation at a time
4. Use Named Colors - red, blue, green, white, etc.
5. Start with Longer Periods - 3-5 seconds, then adjust as needed

Loading DSL Files

Save your DSL code in .anim files and load them:

import animation

# Load DSL file
var runtime = animation.load_dsl_file("my_animation.anim")

User-Defined Functions

Create custom animation functions in Berry and use them in DSL:

# Define custom function - engine must be first parameter
def my_sparkle(engine, color, density, speed)
  var anim = animation.twinkle_animation(engine)
  anim.color = color
  anim.density = density
  anim.speed = speed
  return anim
end

# Register for DSL use
animation.register_user_function("sparkle", my_sparkle)

# Use in DSL - engine is automatically passed
animation gold_sparkles = sparkle(#FFD700, 8, 500ms)
run gold_sparkles

Note: The DSL automatically passes engine as the first argument to user functions.

Next Steps

• DSL Reference - Complete DSL syntax and features
• User Functions - Create custom animation functions
• Examples - More complex animation examples
• Animation Class Hierarchy - All available animations and parameters
• Oscillation Patterns - Dynamic value patterns
• Troubleshooting - Common issues and solutions

Happy animating! 🎨✨