On this page

Home Assistant Setup Guide

Complete installation and configuration reference.

Prerequisites

Before installing, make sure you have the following:

Home Assistant 2024.1 or later
HACS (Home Assistant Community Store) installed

If you don't have HACS yet, visit the HACS installation guide to get set up first.

Installation

Open HACS in your Home Assistant sidebar.
Click the three dots menu (top right) and select Custom repositories.
Add https://github.com/FrogStoneMedia/paddle-conditions as an Integration.
Search for "Paddle Conditions" in HACS and click Install.
Restart Home Assistant.
Go to Settings → Devices & Services → Add Integration and search for "Paddle Conditions".

Configuration

Adding a location

Choose from presets (Lake Natoma, Sand Harbor, and others) or enter custom coordinates for any spot. Each location is tracked independently.

Activity profiles

Select your sport (SUP, Kayak) and context (recreational, racing, family, flatwater, river, ocean). The scoring algorithm adjusts thresholds based on your profile.

Data sources

Open-Meteo — Required, automatic. Provides weather data at no cost.
USGS Water Services — Optional. Adds water temperature and streamflow from monitoring stations.
NOAA CO-OPS — Optional. Adds tides and coastal data for ocean and bay locations.

Update interval

Configurable from 5 to 60 minutes. Default is 30 minutes. Lower intervals use more API calls but keep your data fresher.

Entities

Each configured location exposes the following entities in Home Assistant:

Entity	Description	Unit
paddle_score	Overall condition score (0-100)	score
wind_speed	Current wind speed	mph
wind_gusts	Wind gust speed	mph
wind_direction	Wind direction	degrees
air_temperature	Air temperature	°F
water_temperature	Water temperature (requires USGS)	°F
uv_index	UV index	index
aqi	Air quality index	index
visibility	Visibility distance	miles
precipitation_chance	Chance of precipitation	%
streamflow	Water flow rate (requires USGS)	ft³/s
conditions	Text summary of current conditions	text
forecast_3h	3-hour block forecast data	JSON

Dashboard Cards

Two custom Lovelace cards are included: paddle-score-card and paddle-spots-card. Both are automatically registered when the integration is installed — no manual resource setup needed.

paddle-score-card

type: custom:paddle-score-card
entity: sensor.lake_natoma_paddle_score

paddle-spots-card

type: custom:paddle-spots-card

Customization

Scoring uses 7 weighted factors: wind speed, gusts, AQI, temperature, UV, visibility, and precipitation. Weights shift based on your activity profile.

Hard vetoes apply automatically: thunderstorms and extreme wind set the score to 0 regardless of other factors.

Multiple locations can be added and compared side by side. Each location has its own independent activity profile.

Want even more granularity? PREMIUM Premium offers precision locations for different areas of the same body of water.

Troubleshooting

No data showing

Check that the integration is properly configured under Settings → Devices & Services. If you're using USGS or NOAA, verify that your station IDs are correct.

Wrong temperature

If water temperature seems off, check your USGS station ID. Some stations report air temperature, not water temperature. Cross-reference with the USGS Water Resources site.

Slow updates

Data is cached between updates. The default interval is 30 minutes. Lower intervals use more API calls but deliver fresher data.

Debug logging

Add the following to your configuration.yaml:

logger:
  logs:
    custom_components.paddle_conditions: debug

FAQ

Is it free?

Yes, completely free and open source. MIT license.

Does it need internet?

Yes, to fetch data from weather APIs. All processing is local on your Home Assistant instance.

Can I use it without HACS?

Yes. You can manually install by copying the integration to your custom_components/ directory. See the GitHub repo for details.

How often does data update?

Configurable, with a default of every 30 minutes. Minimum is 5 minutes.