197 lines
3.9 KiB
Markdown
197 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```dsl
|
|
# 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:
|
|
|
|
```dsl
|
|
# 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:
|
|
|
|
```dsl
|
|
# 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:
|
|
|
|
```dsl
|
|
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:
|
|
|
|
```dsl
|
|
# 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
|
|
```dsl
|
|
animation fire = rich_palette(
|
|
palette=PALETTE_FIRE,
|
|
cycle_period=2s,
|
|
transition_type=1
|
|
)
|
|
|
|
run fire
|
|
```
|
|
|
|
### Ocean Waves
|
|
```dsl
|
|
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:
|
|
|
|
```berry
|
|
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:
|
|
|
|
```berry
|
|
# 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)
|
|
```
|
|
|
|
```dsl
|
|
# 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](DSL_REFERENCE.md)** - Complete DSL syntax and features
|
|
- **[User Functions](USER_FUNCTIONS.md)** - Create custom animation functions
|
|
- **[Examples](EXAMPLES.md)** - More complex animation examples
|
|
- **[Animation Class Hierarchy](ANIMATION_CLASS_HIERARCHY.md)** - All available animations and parameters
|
|
- **[Oscillation Patterns](OSCILLATION_PATTERNS.md)** - Dynamic value patterns
|
|
- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions
|
|
|
|
Happy animating! 🎨✨ |