[RELEASE] Trajectory Weather Labs (Predict the surge. Control the outcome)

🚧 Developers Vibe-Code
1

:rocket: Trajectory Weather Labs

"Predict the surge. Control the outcome."

Trajectory Weather Labs is a professional-grade meteorological engine for Hubitat that moves beyond simple weather display into forensic analysis. By leveraging Linear Trend Extrapolation and a weighted "Forensic DNA" algorithm, it predicts severe weather events—Storms, Floods, and Freezes—up to 1 hour in advance, empowering your smart home to take preemptive action.

It transforms your local weather station (Ecowitt, Ambient, etc.) from a passive display into a tactical hazard control center.

:bulb: The Inspiration

I chose Hubitat for one primary reason: 100% local control.

Like many of you, I needed a smart home that didn't depend on the internet to keep my family safe. While there are plenty of weather drivers available, I found they all suffered from the same problem: they rely on data from airports or API services 10–30 miles away.

In my area, the weather in my backyard can be drastically different from what’s happening across town. Relying on distant sensors meant my automations were often triggering too late, or for conditions that weren't actually hitting my house.

I developed Trajectory Weather Labs because I needed microclimate intelligence. I didn't just want a trigger that said, "It is raining." I needed a physics engine that could predict bad weather before it became a problem—using my data from my sensors.

:shield: The Safety Stack: NOAA + TWL

It is critical to state that while this app is fleshed out and functional, it does not replace a NOAA Weather Radio. We cannot predict what is happening 50 miles away, only the trends and history occurring right here.

We use this app as a hyper-local companion to the NOAA system:

  • NOAA: Warns us of what is coming from the next county over.
  • Trajectory Labs: Confirms exactly when it hits our property and how severe the local impact is.

My Use Case: We use the app’s virtual "Storm" and "Warning" switches to trigger minute-by-minute announcements on our house speakers. This keeps our family updated on exactly what is happening outside our windows in real-time, without needing to check our phones or rely on cloud services that might go down during a storm.

:star2: Key Features

1. :dna: Forensic DNA Analysis

Unlike standard apps that trigger on a single data point (e.g., "Wind > 50mph"), Trajectory Labs employs a "molecular" approach. It decomposes every hazard into weighted risk factors that aggregate into a precise Hazard Score (0-100%).

  • :tornado: Storm DNA: Kinetic Energy (Gusts/Wind) + Mass Loading (Rain Rate) + Electrical Surge (Lightning) + Atmospheric Potential (Dew Point/Lux).
  • :ocean: Flood DNA: Hydraulics (Soil Saturation) + Surface Velocity (Runoff Rate).
  • :snowflake: Freeze DNA: Thermodynamics (Wet Bulb/Air Temp) + Crystal Growth (Humidity) + Advection (Wind Direction).

Why this matters: A 30mph wind alone might not be a storm. But 30mph wind + heavy rain + rapid pressure drop + lightning strikes? That is a storm. The DNA engine recognizes this compound risk.

2. :crystal_ball: Predictive "Watch" System (1-Hour Forecast)

The system calculates the Rate of Change (RoC) for every sensor over the last 60 minutes to project future conditions.

  • Linear Trend Extrapolation: Uses the formula Future_Val = Current_Val + (Rate * 1.0hr) to predict future states.
  • Pre-Alert Watches: If the projected risk breaches your safety threshold, it activates a "Watch" switch (e.g., Pre-Storm).
  • Visual Indicators: The dashboard displays trends as STABLE, RISING, or HIGH RISK.

3. :shield: Live Hazard Control Center

Provides real-time monitoring with instant relay activation for automation.

  • Three Distinct Alarm Channels: Storm, Flood, and Freeze.
  • Actionable Automation:
    • Storm Alarm: Retract awnings, close shutters, trigger visual alerts (Red lights).
    • Flood Alarm: Cut power to basement outlets, notify regarding sump pumps.
    • Freeze Alarm: Activate pipe heaters, drip faucets, adjust thermostat setpoints.
  • Smart Hysteresis: Features a "Latch" mechanism (default 20 mins) to prevent alarms from "flapping" on/off during temporary lulls.

4. :brain: Regional Physics Calibration

Acknowledging that a storm in Arizona differs from one in Florida, This version introduces a Regional Physics Module that auto-calibrates based on your US State.

  • Soil Hydraulics: Adjusts flood saturation models for Clay (Midwest) vs. Sand (Coastal).
  • Evaporation Rates: Tunes drying times for Arid vs. Humid climates.
  • Thermal Thresholds: Calibrates freeze warnings for northern vs. southern infrastructure resilience.

5. :satellite: Advanced Sensor Health & Trust

The system is self-aware of data integrity.

  • Stale Data Detection: Flags sensors that stop reporting for >1 hour.
  • Smart Overrides: If the Lightning sensor fails but Wind/Pressure sensors indicate a storm (DNA > 40%), the system intelligently bypasses the stale data to maintain protection.
  • PAI Trust Scores: Displays a "Trust Percentage" for every hazard calculation.

:desktop_computer: The Dashboard (UI)

The app generates a sophisticated, data-rich HTML dashboard directly within the Hubitat mobile app interface.

  • Emergency Protocols: Prominent red/blue banners appear only when critical safety actions are required (e.g., "SEEK SHELTER").
  • Tactical Situation Report: A plain-English text summary of the current threat level (e.g., "Wind: Elevated breeze. Trends: Gusts Surging.").
  • Visual Gauges: Progress bars indicate proximity to alarm triggers.
  • Sparklines: Embedded mini-graphs visualize the last 50 data points for Temp, Rain, and Wind.

:hammer_and_wrench: Installation & Setup

  1. Install Code: Copy the provided Groovy code into Apps Code on your Hubitat hub.
  2. Add App: Navigate to Apps > Add User App > Trajectory Weather Labs.
  3. Select Sensors:
  • Primary: Your Weather Station device (supports drivers with temperature, humidity, windSpeed, rainRate).
  • Optional: Dedicated Lightning Detector (e.g., Ecowitt Wittboy), Lux Sensor.
  1. Configure Relays: Assign virtual switches for Storm, Flood, and Freeze alarms.
  2. Calibrate: (Optional) Visit Regional Physics to select your state for auto-tuning.

:gear: How It Works (The Math)

The Normalization Algorithm

The system normalizes diverse sensor inputs into a unified risk score:

$$Score = \left( \frac{\sum \text{Active Weights}}{\sum \text{Total Possible Weights}} \right) \times 100$$

  • Note: If a sensor (e.g., Lux) is missing, its weight is removed from the denominator, ensuring the score remains an accurate 0-100% representation based on available data.

The "Peak Latching" Logic

To avoid missing gusts between polling cycles, the system employs Peak Latching. It retains the highest wind gust or rain rate recorded in the last 60 minutes for risk calculations, maintaining alert readiness even if live readings temporarily drop.

The "Wet Bulb" Calculation

Calculates Wet Bulb Temperature to predict "Flash Freezing" risks.

  • Standard Freeze: Air Temp < 32°F.
  • Wet Bulb Freeze: Even if Air Temp is 36°F, low humidity can drop the Wet Bulb to 30°F. Evaporation will cool wet surfaces (like pipes) to 30°F, causing bursts despite "above freezing" air. Trajectory Labs detects this hidden danger.
7 Likes
2
2 Likes
3

TWJ_Screen1
TWJ_Screen11508Ă—843 37.9 KB

TWJ_Screen2
TWJ_Screen21538Ă—861 56.8 KB

TWJ_Screen3
TWJ_Screen31520Ă—872 61.8 KB

TWJ_Screen4
TWJ_Screen41541Ă—840 67.4 KB

TWJ_Screen5
TWJ_Screen51544Ă—899 53.9 KB

TWJ_Screen6
TWJ_Screen61517Ă—857 64.6 KB

TWJ_Screen7
TWJ_Screen71519Ă—872 53 KB

1 Like
5

:electric_plug: Hubitat Hub Compatibility & Performance Guide

Trajectory Weather Labs is compatible with all modern Hubitat Elevation hubs (C-5, C-7, C-8, C-8 Pro). However, because the app performs "heavy" logic (writing large history objects to the database and running physics math every cycle), the performance experience differs by model.

1. Hubitat Elevation Model C-5 & C-7 (Standard / Legacy)

  • Architecture: 1.4 GHz CPU / 1GB RAM.
  • How it handles:
    • Performance: Capable of running the engine, but acts as a "Heavy" app.
    • Polling Constraint: It is strongly recommended to set the Trigger Delay (Polling Interval) to 15 Minutes or higher.
    • Risk: Setting the polling to "1 Minute" on these hubs may cause "Database Fragmentation" or general hub slowdowns over time, as the processor struggles to write 50+ history states to the database every 60 seconds while managing other devices.
  • Verdict: :white_check_mark: Compatible (Best for "Standard" use, not "Forensic" speed).

2. Hubitat Elevation Model C-8 (Enhanced Radio)

  • Architecture: 1.4 GHz CPU / 1GB RAM (Same logic speed as C-7) / External Antennas.
  • How it handles:
    • Performance: Logic execution speed is identical to the C-7.
    • Sensor Benefit: The External Antennas significantly improve signal reliability for local sensors (Z-Wave/Zigbee). If your Weather Station (e.g., Ecowitt Gateway or Z-Wave Rain Sensor) is far from the hub, the C-8 ensures fewer "Stale Data" warnings in the app.
    • Verdict: :white_check_mark: Compatible (Improved sensor reliability, same logic constraints as C-7).

3. Hubitat Elevation Model C-8 Pro (The "Forensic" Beast)

  • Architecture: 2.0 GHz CPU / 2GB RAM.
  • How it handles:
    • Performance: The upgraded CPU and doubled RAM make this the ideal platform. The C-8 Pro handles the Groovy math calculations and state object commits roughly 2x faster than the C-7/C-8.
    • Unlocks Potential: You can safely run the app at 1 Minute Polling Intervals ("Forensic Mode") with minimal impact on the rest of your home automation.
    • Verdict: :rocket: Recommended (Required for maximum precision and 1-minute updates).

:trophy: The "Best Recommendation"

  • For Power Users (Forensic Mode): Hubitat C-8 Pro.
    • If you want to use the 1-minute update frequency to catch rapid wind gusts or flash floods instantly, the C-8 Pro's extra RAM is necessary to handle the database load without slowing down your lights and other automations.
    • Why: The "Forensic DNA" engine writes to the database frequently. The C-8 Pro eats this load for breakfast.
  • For Standard Users: Hubitat C-7 or C-8.
    • If you are happy with updates every 15 minutes (which is sufficient for 95% of storm tracking), your existing C-7 or C-8 is perfectly adequate. Just avoid the "1 Minute" setting.

:question: Frequently Asked Questions (FAQ)

General Overview

Q: What is the primary purpose of Trajectory Weather Labs? A: Unlike standard weather apps that display current conditions, this engine is designed to "Predict the surge. Control the outcome.". It acts as a forensic meteorological engine that uses Linear Trend Extrapolation and a "Forensic DNA" scoring system to predict storms, floods, and freezes up to 1 hour in advance.

Q: What is the difference between a "Watch" and a "Warning" in this system? A:

  • :crystal_ball: Watch (Predictive): This is triggered by the Predictive Control Center. It activates when the forecasted risk (1 hour out) combined with current trends exceeds a safety threshold (default 50%). It warns you that conditions are developing.
  • :rotating_light: Warning/Alarm (Live): This is triggered by the Hazard Control Center. It activates when real-time sensor data actually breaches your critical safety limits (e.g., Wind Gust > 35mph and Rain > 1 in/hr) .

Hardware & Sensors

Q: What sensors are required to run this app? A: At a minimum, you need a local Weather Station capable of reporting:

  • Temperature
  • Humidity
  • Wind Speed & Gust (can be excluded via settings, but not recommended)
  • Rain Rate (can be excluded)

Q: Can I use a dedicated lightning sensor? A: Yes. The app supports a dedicated Lightning Sensor (like the Ecowitt Wittboy or WH57). If you don't have one, it can attempt to read lightning data from the main weather device, or you can exclude lightning data entirely from the risk algorithm.

Q: What happens if my sensor stops reporting data? A: The system includes a "Stale Data" safety feature. If a sensor hasn't updated in over 1 hour, the system flags it as stale.

  • General Sensors: If the main station is stale (>1h), the system enters "Safe Mode" and halts logic to prevent false automation .
  • Lightning Sensor: If lightning data is stale (>1h), it is usually ignored. However, if other storm indicators (Wind/Rain) are high (>40%), the "Storm Override" kicks in and uses the last known lightning data, ensuring you don't lose protection during a severe event just because the sensor went offline .

The "Forensic DNA" Logic

Q: How is the "Hazard Score" calculated? A: The score (0-100%) is a weighted average of all active risk factors, not just a single reading.

  • Storm DNA: Includes Gusts, Sustained Wind, Rain Rate, Lightning Surge, Proximity, Dew Point energy, and Lux (darkness) .
  • Flood DNA: Combines "Runoff" (how fast rain is falling) with "Soil Saturation" (how wet the ground already is) .
  • Freeze DNA: Analyzes Temperature, "Vapor Load" (humidity), Advection (wind direction), and Wet Bulb temperature .

Q: What is "Peak Latching" and why is it used? A: Peak Latching prevents alarms from "flapping" (turning on and off rapidly). The system remembers the maximum wind gust or rain rate from the last 60 minutes. If a gust hits 40mph and then drops to 10mph, the system "locks" that 40mph risk for an hour to keep your home in a defensive state until the storm truly passes.

Q: Why is "Wet Bulb" included in the Freeze calculation? A: Wet Bulb temperature is critical for predicting flash freezing. Even if the air temperature is above freezing (e.g., 36°F), if the humidity is low, the Wet Bulb can be below 32°F. This means evaporation will cool wet surfaces (like pipes or plants) to freezing levels, causing damage despite the "safe" air temperature.

Calibration & Configuration

Q: What is "Regional Physics" and how do I use it? A: This feature calibrates the math engine based on your location. You select your US State in the settings. The system then adjusts:

  • Soil Hydraulics: Clay vs. Sand saturation rates (e.g., Florida gets Sand, Midwest gets Clay) .
  • Wind Profiles: Adjusts gust baselines for Tropical vs. Arctic vs. Convective environments.
  • Thermal Thresholds: Sets different freeze warning levels for different climates.

Q: How can I stop false alarms from notification spam? A: You can adjust the Trigger Delay in the settings (recommended 30-60 mins). This forces the system to wait and confirm conditions before sending alerts. Additionally, the Peak Latching feature naturally smooths out erratic sensor data to prevent rapid toggling.

Q: What does the "Trigger Delay" setting do? A: It defines how often the app wakes up to process data and run physics calculations.

  • 1-5 Mins: Maximum speed, high battery drain.
  • 15 Mins: Balanced standard.
  • 30-60 Mins: Battery saver; prevents "flapping" notifications.

Troubleshooting

Q: Why does the dashboard say "SYSTEM MUTED"? A: You (or someone else) likely pressed the "MUTE ALL (24H)" button on the control deck. This suppresses all notifications and automation triggers for 24 hours. You can unmute it manually or wait for the timer to expire.

Q: What do the status colors on the dashboard mean? A:

  • Green: STABLE / READY.
  • Orange: RISING / PRE-ALERT (Watch Active).
  • Red: HIGH / IMMINENT (Alarm Active).
  • Purple: TEST/SIMULATION MODE.
  • Grey: WAITING / NO DATA.

Q: Why are there "Emerg Protocols" banners on my dashboard? A: These only appear when a live Emergency Protocol is active (Score > Limit).

  • Red Banner: Storm Protocol (Seek Shelter).
  • Blue Banner: Flood Protocol (Move to higher ground).
  • Grey/Black Banner: Freeze Protocol (Protect pipes).
6

I dont see this in HPM? Have to manually add as an app or driver code?

7

At this time, the app is not available via the Hubitat Package Manager. I appreciate your patience as I work toward making it available there in a future update.

1 Like