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

# Troubleshooting Guide

Common issues and solutions for the Tasmota Berry Animation Framework.

**Note**: This guide focuses on DSL usage, which is the recommended way to create animations. For programmatic API issues, see the [Animation Development Guide](ANIMATION_DEVELOPMENT.md).

## Installation Issues

### Framework Not Found

**Problem:** `import animation` or `import animation_dsl` fails with "module not found"

**Solutions:**
1. **Check Module Import:**
   ```berry
   import animation      # Core framework
   import animation_dsl  # DSL compiler
   ```

2. **Set Module Path:**
   ```bash
   berry -m lib/libesp32/berry_animation
   ```

3. **Verify File Structure:**
   ```
   lib/libesp32/berry_animation/
   ├── animation.be          # Main module file
   ├── dsl/                  # DSL components
   ├── core/                 # Core classes
   ├── animations/           # Animation effects
   └── ...
   ```

### Missing Dependencies

**Problem:** Errors about missing `tasmota` or `Leds` classes

**Solutions:**
1. **For Tasmota Environment:**
   - Ensure you're running on actual Tasmota firmware
   - Check that Berry support is enabled

2. **For Development Environment:**
   ```berry
   # Mock Tasmota for testing
   if !global.contains("tasmota")
     global.tasmota = {
       "millis": def() return 1000 end,
       "scale_uint": def(val, from_min, from_max, to_min, to_max)
         return int((val - from_min) * (to_max - to_min) / (from_max - from_min) + to_min)
       end
     }
   end
   ```

## Animation Issues

### Animations Not Starting

**Problem:** DSL animations compile but LEDs don't change

**Diagnostic Steps:**
```berry
import animation
import animation_dsl

# Test basic DSL execution
var dsl_code = "color red = 0xFF0000\n" +
               "animation red_anim = solid(color=red)\n" +
               "run red_anim"

try
  animation_dsl.execute(dsl_code)
  print("DSL executed successfully")
except .. as e, msg
  print("DSL Error:", msg)
end
```

**Common Solutions:**

1. **Missing Strip Declaration:**
   ```dsl
   # Add explicit strip length if needed
   strip length 30
   
   color red = 0xFF0000
   animation red_anim = solid(color=red)
   run red_anim
   ```

2. **Animation Not Executed:**
   ```dsl
   # Make sure you have a 'run' statement
   color red = 0xFF0000
   animation red_anim = solid(color=red)
   run red_anim  # Don't forget this!
   ```

3. **Strip Auto-Detection Issues:**
   ```dsl
   # Force strip length if auto-detection fails
   strip length 30  # Must be first statement
   
   color red = 0xFF0000
   animation red_anim = solid(color=red)
   run red_anim
   ```

### Colors Look Wrong

**Problem:** Colors appear different than expected

**Common Issues:**

1. **Missing Alpha Channel:**
   ```dsl
   # Note: 0xFF0000 is valid RGB format (alpha defaults to 0xFF)
   color red = 0xFF0000      # RGB format (alpha=255 assumed)
   
   # Explicit alpha channel (ARGB format)
   color red = 0xFFFF0000    # ARGB format (alpha=255, red=255)
   color semi_red = 0x80FF0000  # ARGB format (alpha=128, red=255)
   ```

2. **Color Format Confusion:**
   ```dsl
   # ARGB format: 0xAARRGGBB
   color red = 0xFFFF0000      # Alpha=FF, Red=FF, Green=00, Blue=00
   color green = 0xFF00FF00    # Alpha=FF, Red=00, Green=FF, Blue=00
   color blue = 0xFF0000FF     # Alpha=FF, Red=00, Green=00, Blue=FF
   ```

3. **Brightness Issues:**
   ```dsl
   # Use opacity parameter or property assignment
   animation red_anim = solid(color=red, opacity=255)  # Full brightness
   
   # Or assign after creation
   animation pulse_red = pulsating_animation(color=red, period=2s)
   pulse_red.opacity = 200  # Adjust brightness
   
   # Use value providers for dynamic brightness
   set brightness = smooth(min_value=50, max_value=255, period=3s)
   animation breathing = solid(color=red)
   breathing.opacity = brightness
   ```

### Animations Too Fast/Slow

**Problem:** Animation timing doesn't match expectations

**Solutions:**

1. **Check Time Units:**
   ```dsl
   # DSL uses time units (converted to milliseconds)
   animation pulse_anim = pulsating_animation(color=red, period=2s)    # 2 seconds
   animation fast_pulse = pulsating_animation(color=blue, period=500ms) # 0.5 seconds
   ```

2. **Adjust Periods:**
   ```dsl
   # Too fast - increase period
   animation slow_pulse = pulsating_animation(color=red, period=5s)   # 5 seconds
   
   # Too slow - decrease period
   animation fast_pulse = pulsating_animation(color=red, period=500ms) # 0.5 seconds
   ```

3. **Performance Limitations:**
   ```dsl
   # Use sequences instead of multiple simultaneous animations
   sequence optimized_show {
     play animation1 for 3s
     play animation2 for 3s
     play animation3 for 3s
   }
   run optimized_show
   
   # Instead of:
   # run animation1
   # run animation2  
   # run animation3
   ```

## DSL Issues

### DSL Compilation Errors

**Problem:** DSL code fails to compile

**Diagnostic Approach:**
```berry
try
  var berry_code = animation_dsl.compile(dsl_source)
  print("Compilation successful")
except "dsl_compilation_error" as e, msg
  print("DSL Error:", msg)
end
```

**Common DSL Errors:**

1. **Undefined Colors:**
   ```dsl
   # Wrong - color not defined
   animation red_anim = solid(color=red)
   
   # Correct - define color first
   color red = 0xFF0000
   animation red_anim = solid(color=red)
   ```

2. **Invalid Color Format:**
   ```dsl
   # Wrong - # prefix not supported (conflicts with comments)
   color red = #FF0000
   
   # Correct - use 0x prefix
   color red = 0xFF0000
   ```

3. **Missing Time Units:**
   ```dsl
   # Wrong - no time unit
   animation pulse_anim = pulsating_animation(color=red, period=2000)
   
   # Correct - with time unit
   animation pulse_anim = pulsating_animation(color=red, period=2s)
   ```

4. **Reserved Name Conflicts:**
   ```dsl
   # Wrong - 'red' is a predefined color
   color red = 0x800000
   
   # Correct - use different name
   color dark_red = 0x800000
   ```

5. **Invalid Parameter Names:**
   ```dsl
   # Wrong - invalid parameter name
   animation pulse_anim = pulsating_animation(color=red, invalid_param=123)
   # Error: "Parameter 'invalid_param' is not valid for pulsating_animation"
   
   # Correct - use valid parameters (see DSL_REFERENCE.md for complete list)
   animation pulse_anim = pulsating_animation(color=red, period=2s)
   ```

6. **Parameter Constraint Violations:**
   ```dsl
   # Wrong - negative period not allowed
   animation bad_pulse = pulsating_animation(color=red, period=-2s)
   # Error: "Parameter 'period' value -2000 violates constraint: min=1"
   
   # Wrong - invalid enum value
   animation bad_comet = comet_animation(color=red, direction=5)
   # Error: "Parameter 'direction' value 5 not in allowed values: [-1, 1]"
   
   # Correct - valid parameters within constraints
   animation good_pulse = pulsating_animation(color=red, period=2s)
   animation good_comet = comet_animation(color=red, direction=1)
   ```

### DSL Runtime Errors

**Problem:** DSL compiles but fails at runtime

**Common Issues:**

1. **Strip Not Initialized:**
   ```dsl
   # Add strip declaration if needed
   strip length 30
   
   color red = 0xFF0000
   animation red_anim = solid(color=red)
   run red_anim
   ```

2. **Sequence Issues:**
   ```dsl
   # Make sure animations are defined before sequences
   color red = 0xFF0000
   animation red_anim = solid(color=red)  # Define first
   
   sequence demo {
     play red_anim for 3s  # Use after definition
     wait 1s               # Optional pause between animations
   }
   run demo
   ```

3. **Undefined References:**
   ```dsl
   # Wrong - using undefined animation in sequence
   sequence bad_demo {
     play undefined_animation for 3s
   }
   # Error: "Undefined reference: 'undefined_animation'"
   
   # Correct - define all references first
   color blue = 0x0000FF
   animation blue_anim = solid(color=blue)
   
   sequence good_demo {
     play blue_anim for 3s
   }
   run good_demo
   ```

## Performance Issues

### Choppy Animations

**Problem:** Animations appear jerky or stuttering

**Solutions:**

1. **Use Sequences Instead of Multiple Animations:**
   ```dsl
   # Good - sequential playback
   sequence smooth_show {
     play animation1 for 3s
     play animation2 for 3s
     play animation3 for 3s
   }
   run smooth_show
   
   # Avoid - too many simultaneous animations
   # run animation1
   # run animation2
   # run animation3
   ```

2. **Increase Animation Periods:**
   ```dsl
   # Smooth - longer periods
   animation smooth_pulse = pulsating_animation(color=red, period=3s)
   
   # Choppy - very short periods
   animation choppy_pulse = pulsating_animation(color=red, period=50ms)
   ```

3. **Optimize Value Providers:**
   ```dsl
   # Efficient - reuse providers
   set breathing = smooth(min_value=50, max_value=255, period=2s)
   
   color red = 0xFF0000
   color blue = 0x0000FF
   
   animation anim1 = pulsating_animation(color=red, period=2s)
   anim1.opacity = breathing
   
   animation anim2 = pulsating_animation(color=blue, period=2s)
   anim2.opacity = breathing  # Reuse same provider
   ```

### Memory Issues

**Problem:** Out of memory errors or system crashes

**Solutions:**

1. **Clear Unused Animations:**
   ```berry
   # Clear before adding new animations
   engine.clear()
   engine.add_animation(new_animation)
   ```

2. **Limit Palette Size:**
   ```dsl
   # Good - reasonable palette size
   palette simple_fire = [
     (0, #000000),
     (128, #FF0000),
     (255, #FFFF00)
   ]
   
   # Avoid - very large palettes
   # palette huge_palette = [
   #   (0, color1), (1, color2), ... (255, color256)
   # ]
   ```

3. **Use Sequences Instead of Simultaneous Animations:**
   ```dsl
   # Memory efficient - sequential playback
   sequence show {
     play animation1 for 5s
     play animation2 for 5s
     play animation3 for 5s
   }
   
   # Memory intensive - all at once
   # run animation1
   # run animation2
   # run animation3
   ```

## Event System Issues

### Events Not Triggering

**Problem:** Event handlers don't execute

**Diagnostic Steps:**
```berry
# Check if handler is registered
var handlers = animation.get_event_handlers("button_press")
print("Handler count:", size(handlers))

# Test event triggering
animation.trigger_event("test_event", {"debug": true})
```

**Solutions:**

1. **Verify Handler Registration:**
   ```berry
   def test_handler(event_data)
     print("Event triggered:", event_data)
   end
   
   var handler = animation.register_event_handler("test", test_handler, 0)
   print("Handler registered:", handler != nil)
   ```

2. **Check Event Names:**
   ```berry
   # Event names are case-sensitive
   animation.register_event_handler("button_press", handler)  # Correct
   animation.trigger_event("button_press", {})               # Must match exactly
   ```

3. **Verify Conditions:**
   ```berry
   def condition_func(event_data)
     return event_data.contains("required_field")
   end
   
   animation.register_event_handler("event", handler, 0, condition_func)
   
   # Event data must satisfy condition
   animation.trigger_event("event", {"required_field": "value"})
   ```

## Hardware Issues

### LEDs Not Responding

**Problem:** Framework runs but LEDs don't light up

**Hardware Checks:**

1. **Power Supply:**
   - Ensure adequate power for LED count
   - Check voltage (5V for WS2812)
   - Verify ground connections

2. **Wiring:**
   - Data line connected to correct GPIO
   - Ground connected between controller and LEDs
   - Check for loose connections

3. **LED Strip:**
   - Test with known working code
   - Check for damaged LEDs
   - Verify strip type (WS2812, SK6812, etc.)

**Software Checks:**
```berry
# Test basic LED functionality
var strip = Leds(30)  # 30 LEDs
strip.set_pixel_color(0, 0xFFFF0000)  # Set first pixel red
strip.show()  # Update LEDs

# Test with animation framework
import animation
var engine = animation.create_engine(strip)
var red_anim = animation.solid(engine)
red_anim.color = 0xFFFF0000
engine.add_animation(red_anim)
engine.start()

# If basic strip works but animation doesn't, check framework setup
```

### Wrong Colors on Hardware

**Problem:** Colors look different on actual LEDs vs. expected

**Solutions:**

1. **Color Order:**
   ```berry
   # Some strips use different color orders
   # Try different strip types in Tasmota configuration
   # WS2812: RGB order
   # SK6812: GRBW order
   ```

2. **Gamma Correction:**
   ```berry
   # Enable gamma correction in Tasmota
   # SetOption37 128  # Enable gamma correction
   ```

3. **Power Supply Issues:**
   - Voltage drop causes color shifts
   - Use adequate power supply
   - Add power injection for long strips

## Debugging Techniques

### DSL vs Berry API Debugging

**For DSL Issues (Recommended):**
```berry
# Enable DSL debug output
import animation_dsl

var dsl_code = "color red = 0xFF0000\nanimation test = solid(color=red)\nrun test"

# Check compilation
try
  var berry_code = animation_dsl.compile(dsl_code)
  print("DSL compilation successful")
  print("Generated Berry code:")
  print(berry_code)
except .. as e, msg
  print("DSL compilation error:", msg)
end

# Execute with debug
try
  animation_dsl.execute(dsl_code, true)  # debug=true
except .. as e, msg
  print("DSL execution error:", msg)
end
```

**For Framework Issues (Advanced):**
```berry
# Direct Berry API debugging (for framework developers)
import animation

var strip = Leds(30)
var engine = animation.create_engine(strip, true)  # debug=true

var anim = animation.solid(engine)
anim.color = 0xFFFF0000
engine.add_animation(anim)
engine.start()
```

### Step-by-Step Testing

```berry
# Test each component individually
print("1. Creating strip...")
var strip = Leds(30)
print("Strip created:", strip != nil)

print("2. Creating engine...")
var engine = animation.create_engine(strip)
print("Engine created:", engine != nil)

print("3. Creating animation...")
var anim = animation.solid(engine)
anim.color = 0xFFFF0000
print("Animation created:", anim != nil)

print("4. Adding animation...")
engine.add_animation(anim)
print("Animation count:", engine.size())

print("5. Starting engine...")
engine.start()
print("Engine active:", engine.is_active())
```

### Monitor Performance

```berry
# Check timing
var start_time = tasmota.millis()
# ... run animation code ...
var end_time = tasmota.millis()
print("Execution time:", end_time - start_time, "ms")

# Monitor memory (if available)
import gc
print("Memory before:", gc.allocated())
# ... create animations ...
print("Memory after:", gc.allocated())
```

## Getting Help

### Information to Provide

When asking for help, include:

1. **Hardware Setup:**
   - LED strip type and count
   - GPIO pin used
   - Power supply specifications

2. **Software Environment:**
   - Tasmota version
   - Berry version
   - Framework version

3. **Code:**
   - Complete minimal example that reproduces the issue
   - Error messages (exact text)
   - Expected vs. actual behavior

4. **Debugging Output:**
   - Debug mode output
   - Generated Berry code (for DSL issues)
   - Console output

### Example Bug Report

```
**Problem:** DSL animation compiles but LEDs don't change

**Hardware:**
- 30x WS2812 LEDs on GPIO 1
- ESP32 with 5V/2A power supply

**Code:**
```dsl
color red = 0xFF0000
animation red_anim = solid(color=red)
run red_anim
```

**Error Output:**
```
DSL compilation successful
Engine created: true
Animation count: 1
Engine active: true
```

**Expected:** LEDs turn red
**Actual:** LEDs remain off

**Additional Info:**
- Basic `strip.set_pixel_color(0, 0xFFFF0000); strip.show()` works
- Tasmota 13.2.0, Berry enabled
```

This format helps identify issues quickly and provide targeted solutions.

## Prevention Tips

### Code Quality

1. **Use Try-Catch Blocks:**
   ```berry
   try
     runtime.load_dsl(dsl_code)
   except .. as e, msg
     print("Error:", msg)
   end
   ```

2. **Validate Inputs:**
   ```berry
   if type(color) == "int" && color >= 0
     var anim = animation.solid(color)
   else
     print("Invalid color:", color)
   end
   ```

3. **Test Incrementally:**
   - Start with simple solid colors
   - Add one effect at a time
   - Test each change before proceeding

### Performance Best Practices

1. **Limit Complexity:**
   - 1-3 simultaneous animations
   - Reasonable animation periods (>1 second)
   - Moderate palette sizes

2. **Resource Management:**
   - Clear unused animations
   - Reuse value providers
   - Use sequences for complex shows

3. **Hardware Considerations:**
   - Adequate power supply
   - Proper wiring and connections
   - Appropriate LED strip for application

## Quick Reference: Common DSL Patterns

### Basic Animation
```dsl
color red = 0xFF0000
animation red_solid = solid(color=red)
run red_solid
```

### Animation with Parameters
```dsl
color blue = 0x0000FF
animation blue_pulse = pulsating_animation(color=blue, period=2s, opacity=200)
run blue_pulse
```

### Using Value Providers
```dsl
set breathing = smooth(min_value=50, max_value=255, period=3s)
color green = 0x00FF00
animation breathing_green = solid(color=green)
breathing_green.opacity = breathing
run breathing_green
```

### Sequences
```dsl
color red = 0xFF0000
color blue = 0x0000FF

animation red_anim = solid(color=red)
animation blue_anim = solid(color=blue)

sequence demo {
  play red_anim for 2s
  wait 500ms
  play blue_anim for 2s
}
run demo
```

### Multiple Strip Lengths
```dsl
strip length 60  # Must be first statement

color rainbow = rainbow_color_provider(period=5s)
animation rainbow_anim = solid(color=rainbow)
run rainbow_anim
```

Following these guidelines will help you avoid most common issues and create reliable LED animations.