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

Oscillation Patterns

Quick reference for oscillation patterns used with value providers in the Berry Animation Framework.

Available Oscillation Patterns

These waveform constants can be used with oscillator_value:

Constant	Value	Alias Functions	Behavior	Use Case
SAWTOOTH	1	linear, ramp	Linear ramp up	Uniform motion
TRIANGLE	2	triangle	Linear up then down	Sharp direction changes
SQUARE	3	square	Alternating min/max	On/off effects
COSINE	4	smooth	Smooth cosine wave	Natural oscillation
SINE	5	sine	Pure sine wave	Classic wave motion
EASE_IN	6	ease_in	Slow start, fast end	Smooth acceleration
EASE_OUT	7	ease_out	Fast start, slow end	Smooth deceleration
ELASTIC	8	elastic	Spring overshoot	Bouncy effects
BOUNCE	9	bounce	Ball bouncing	Physics simulation

DSL Usage

With Oscillator Value Provider

# Basic oscillator with different waveform types
set breathing = oscillator_value(min_value=50, max_value=255, duration=3000, form=COSINE)
set pulsing = ease_in(min_value=0, max_value=255, duration=2000)
set bouncing = oscillator_value(min_value=10, max_value=240, duration=4000, form=TRIANGLE)

Using Alias Functions

# These are equivalent to oscillator_value with specific forms
set smooth_fade = smooth(min_value=50, max_value=255, duration=3000)      # form=COSINE
set sine_wave = sine(min_value=50, max_value=255, duration=3000)          # form=SINE
set linear_sweep = linear(min_value=0, max_value=255, duration=2000)      # form=SAWTOOTH  
set triangle_wave = triangle(min_value=10, max_value=240, duration=4000)  # form=TRIANGLE

In Animations

color blue = 0x0000FF
set breathing = smooth(min_value=100, max_value=255, duration=4000)

animation breathing_blue = solid(color=blue)
breathing_blue.opacity = breathing
run breathing_blue

Pattern Characteristics

SAWTOOTH (Linear)

• Constant speed throughout the cycle
• Sharp reset from max back to min
• Best for: Uniform sweeps, mechanical movements

Value
  ^
  |     /|     /|
  |    / |    / |
  |   /  |   /  |
  |  /   |  /   |
  | /    | /    |
  |/     |/     |
  +------+------+----> Time

set linear_brightness = linear(min_value=0, max_value=255, duration=2000)

COSINE (Smooth)

• Gradual acceleration and deceleration
• Natural feeling transitions
• Best for: Breathing effects, gentle fades

set breathing_effect = smooth(min_value=50, max_value=255, duration=3000)

SINE (Pure Wave)

• Classic sine wave starting from minimum
• Smooth acceleration and deceleration like cosine but phase-shifted
• Best for: Wave effects, classic oscillations, audio-visual sync

Value
  ^
  |        ___
  |       /   \
  |      /     \
  |     /       \
  |    /         \
  |   /           \
  |  /             \
  | /               \
  |/                 \___
  +--------------------+----> Time

set wave_motion = sine(min_value=0, max_value=255, duration=2000)

TRIANGLE

• Linear acceleration to midpoint, then linear deceleration
• Sharp direction changes at extremes
• Best for: Bouncing effects, sharp transitions

Value
  ^
  |      /\
  |     /  \
  |    /    \
  |   /      \
  |  /        \
  | /          \
  |/            \
  +-------------+----> Time

set bounce_position = triangle(min_value=5, max_value=55, duration=2000)

SQUARE

• Alternating between min and max values
• Instant transitions with configurable duty cycle
• Best for: On/off effects, strobing, digital patterns

Value
  ^
  | +---+     +---+
  | |   |     |   |
  | |   |     |   |
  | |   +-----+   |
  | |             |
  | |             |
  +-+-------------+----> Time

set strobe_effect = square(min_value=0, max_value=255, duration=500, duty_cycle=25)

EASE_IN

• Slow start, fast finish
• Smooth acceleration curve
• Best for: Starting animations, building intensity

set accelerating = ease_in(min_value=0, max_value=255, duration=3000)

EASE_OUT

• Fast start, slow finish
• Smooth deceleration curve
• Best for: Ending animations, gentle stops

set decelerating = ease_out(min_value=255, max_value=0, duration=3000)

Value Progression Examples

For a cycle from 0 to 100 over 2000ms:

Time	SAWTOOTH	COSINE	SINE	TRIANGLE	EASE_IN	EASE_OUT
0ms	0	0	0	0	0	0
500ms	25	15	50	50	6	44
1000ms	50	50	100	100	25	75
1500ms	75	85	50	50	56	94
2000ms	100	100	0	0	100	100

Common Patterns

Breathing Effect

color soft_white = 0xC0C0C0
set breathing = smooth(min_value=80, max_value=255, duration=4000)

animation breathing_light = solid(color=soft_white)
breathing_light.opacity = breathing
run breathing_light

Position Sweep

strip length 60
color red = 0xFF0000
set sweeping_position = linear(min_value=0, max_value=59, duration=3000)

animation position_sweep = beacon_animation(
  color=red,
  position=sweeping_position,
  beacon_size=3,
  fade_size=1
)
run position_sweep

Wave Motion

color purple = 0x8000FF
set wave_brightness = sine(min_value=50, max_value=255, duration=2500)

animation wave_effect = solid(color=purple)
wave_effect.opacity = wave_brightness
run wave_effect

Bouncing Effect

color green = 0x00FF00
set bounce_size = triangle(min_value=1, max_value=8, duration=1000)

animation bouncing_pulse = beacon_animation(
  color=green,
  position=30,
  beacon_size=bounce_size,
  fade_size=1
)
run bouncing_pulse

Accelerating Fade

color blue = 0x0000FF
set fade_in = ease_in(min_value=0, max_value=255, duration=5000)

animation accelerating_fade = solid(color=blue)
accelerating_fade.opacity = fade_in
run accelerating_fade

Strobe Effect

color white = 0xFFFFFF
set strobe_pattern = square(min_value=0, max_value=255, duration=200, duty_cycle=10)

animation strobe_light = solid(color=white)
strobe_light.opacity = strobe_pattern
run strobe_light

Tips

• COSINE (smooth): Most natural for breathing and gentle effects
• SINE: Classic wave motion, perfect for audio-visual sync and pure oscillations
• SAWTOOTH (linear): Best for consistent sweeps and mechanical movements
• TRIANGLE: Creates sharp, bouncing transitions
• EASE_IN: Perfect for building up intensity
• EASE_OUT: Ideal for gentle fade-outs
• ELASTIC: Spring-like effects with overshoot
• BOUNCE: Physics-based bouncing effects
• SQUARE: Good for on/off blinking effects

Choose the oscillation pattern that matches the feeling you want to create in your animation.