Weather Animation
Rain Cloud translates weather data into LED animations. Here's how the system works.
How weather becomes light
Every 15 minutes, the device fetches weather data from Open-Meteo. The raw data goes through two stages:
- Data mapping — raw API data is converted into two intermediate values: rainAmount and rainCountdown
- State selection — these values (plus configurable thresholds) determine which animation state is active
The two key values
How much rain. Represents the intensity of precipitation right now, or the likelihood of rain if it's not currently raining.
| Value | Meaning |
|---|---|
0 | No rain, low probability |
1–50 | Light rain or moderate probability |
50–128 | Moderate rain |
128–192 | Heavy rain |
192–255 | Very heavy / storm (≥50 mm/h maps to 255) |
When it's not currently raining but rain is expected, the amount is derived from the highest probability (2h or 12h). This gives the display a gentle "hint" of upcoming rain.
How soon rain is coming. A rough estimate of hours until precipitation, based on probability thresholds.
| Value | Meaning |
|---|---|
0 | Raining right now (current precipitation > 0) |
2 | Rain likely within 2 hours (2h probability > 50%) |
8 | Rain likely within 12 hours (12h probability > 50%) |
255 | No rain expected |
Animation states
The device has three rain animation states, evaluated in priority order. Each state has its own pulse/decay timing that controls how the three raindrop LED groups light up and fade.
Rain Soon
Highest priority — checked first
Active, fast animation with all 3 drops pulsing frequently.
Default trigger: current precipitation ≥ 0.1 mm/h or 2-hour probability ≥ 80%
Rain Later
Medium priority
Moderate animation with up to 2 drops active.
Default trigger: 2-hour probability ≥ 40% or 12-hour probability ≥ 60%
Rain Today
Lowest priority — checked last
Gentle, slow animation with a single drop pulsing occasionally.
Default trigger: 12-hour probability ≥ 30%
If no thresholds match, the device shows a gentle ambient wave animation (clear sky).
Pulse and decay
Each raindrop group (left, middle, right — 7 LEDs each) follows a simple cycle:
- A pulse timer fires every pulseInterval ms
- A random drop is chosen — if it's already active or the max active limit is reached, nothing happens
- The drop lights up at full brightness
- It decays linearly from full to off over decayDuration ms
Faster pulse intervals and longer decays create more overlap, making the display appear more active. Slower pulses with short decays create sparse, gentle flickers.
Storm mode
When a thunderstorm is detected (WMO weather codes 95–99), storm mode adds a sharp flash before the normal decay:
- Drop flashes ON at full brightness for flashOn ms (default: 80ms)
- Drop goes dark for flashOff ms (default: 60ms)
- Normal decay begins from full brightness
This creates a lightning-like strobe effect layered on top of the rain animation.
Configuring thresholds
Each rain state has three trigger conditions. If any condition is met (they're OR'd together), that state activates. Set a value to 0 to disable that condition.
| Threshold | Description | Unit |
|---|---|---|
| Min Precipitation | Current rainfall rate to trigger this state | mm/h × 10 (so 1 = 0.1 mm/h) |
| Min 2h Probability | 2-hour rain probability to trigger this state | 0–100% |
| Min 12h Probability | 12-hour rain probability to trigger this state | 0–100% |
All animation timing and threshold settings can be changed on the device's local web interface (System tab). Use the animation playground to experiment with timing values before applying them to your device.
Testing
Use the Force Mode control on the device's System tab (or the serial
console: weather force soon) to override the weather state and see each
animation immediately. Set back to none to return to live weather data.