briis / hass-weatherflow2mqtt

WeatherFlow to MQTT for Home Assistant. Use UDP to get local weather data in to Home Assistant using MQTT Discovery
MIT License
129 stars 29 forks source link
docker home-assistant mqtt-smarthome python3 udp-protocol weatherflow

WeatherFlow-2-MQTT for Home Assistant

Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.

BREAKING Announcement

As there is now a Home Assistant Core integration for WeatherFlow which uses the UDP API, I had to make a new Integration that uses the REST API, with a different name (WeatherFlow Forecast). The new integration is up-to-date with the latest specs for how to create a Weather Forecast, and also gives the option to only add the Forecast, and no additional sensors.

There is no Weather Entity in Home Assistant for MQTT, so after attributes are deprecated in Home Assistant 2024.3, there is no option to add the Forecast to Home Assistant. As a consequence of that, I have decided to remove the ability for this Add-On to add Forecast data to MQTT and Home Assistant. This Add-On will still be maintained, but just without the option of a Forecast - meaning it will be 100% local. If you want the forecast in combination with this Add-On, install the new integration mentioned above, just leave the Add sensors box unchecked.

Overview

There is not an exact date for when this will happen, but it will be before end of February 2024. This project monitors the UDP socket (50222) from a WeatherFlow Hub, and publishes the data to a MQTT Server. Data is formatted in a way that, it supports the MQTT Discovery format for Home Assistant, so a sensor will created for each entity that WeatherFlow sends out, if you have MQTT Discovery enabled.

Everything runs in a pre-built Docker Container, so installation is very simple. You only need Docker installed on a computer and a MQTT Server setup somewhere in your network. If you run either the Operating System or Supervised installation of Home Assistant, you will have easy access to both.

There is support for both the AIR & SKY devices and the TEMPEST device.

Please review Breaking Changes prior to updating your instance. Breaking changes will be listed in https://github.com/briis/hass-weatherflow2mqtt/blob/main/CHANGELOG.md

Table of Contents

  1. Installation
  2. Docker Setup
    1. Docker Volume
    2. Docker Environment Variables
  3. Available Sensors
    1. Sensor Structure
    2. High and Low Values
    3. Long Term Statistics
    4. Sensors in Developement
  4. Creating a Home Assistant Weather Entity
  5. Creating a Developement Environment

Installation

Prerequisites

A MQTT Server must be setup and configured on your local network, before installing this component. If you run a Supervised Home Assistant installation, we recommend using the MQTT Add-On available for this, else you must set it up yourself. See more here for installing MQTT.

NOTE: WeatherFlow2MQTT will not discover your base station if it is on a separate VLAN/subnet from your Home Assistant (or Docker) instance.

Home Assistant Supervised

This is the easiest installation method. Just click on the blue ADD REPOSITORY button at the top of this README and you will be taken to your Home Assistant instance to add this repository to the Add-On Store. From there, scroll down to find "WeatherFlow to MQTT" and then install, configure (optional) and start the add-on.

NOTE: Make sure that you already have setup a Working MQTT broker, and easiest way to do that is by using the MQTT broker from the Official Add-On store.

Outside Home Assistant using Docker

If everything is setup correctly with MQTT and Home Assistant, you should now start seeing the sensors show up in HA. NOTE, it can take up to 1 min after startup, before all sensors are populated with data.

Docker Setup

The below command will pull the latest docker image and start WeatherFlow2MQTT for timezone Europe/Copenhagen and save data in the directory you are placed in when you launch the command. Ensure that you have replaced the Environment variables with your specific data. See description below.

If you are using docker-compose you can use the docker-compose.yml file and make the modifications for your environment.

docker run -d \
--name=weatherflow2mqtt --restart=unless-stopped \
-v $(pwd):/data \
-p 0.0.0.0:50222:50222/udp \
-e TZ=Europe/Copenhagen \
-e UNIT_SYSTEM=metric \
-e LANGUAGE=en \
-e RAPID_WIND_INTERVAL=0 \
-e DEBUG=False \
-e ELEVATION=0 \
-e LATITUDE=00.0000 \
-e LONGITUDE=000.0000 \
-e ZAMBRETTI_MIN_PRESSURE=960 \
-e ZAMBRETTI_MAX_PRESSURE=1060 \
-e WF_HOST=0.0.0.0 \
-e WF_PORT=50222 \
-e MQTT_HOST=127.0.0.1 \
-e MQTT_PORT=1883 \
-e MQTT_USERNAME= \
-e MQTT_PASSWORD= \
-e MQTT_DEBUG=False \
-e STATION_ID= \
-e STATION_TOKEN= \
-e FORECAST_INTERVAL=30 \
briis/weatherflow2mqtt:latest

The container is build for both Intel and ARM platforms, so it should work on most HW types. Please create an issue, if there is a platform for which it does not work.

Docker Volume

-v YOUR_STORAGE_AREA:/data Please replace _YOUR_STORAGEAREA with a directory where Docker will have read and write access. Once the program runs, a SQLite Database with the name weatherflow2mqtt.db will be created in this directory. This database is used to hold some calculated values, store temporary data used for calculations and to ensure that you don't start from 0 if you have to restart Home Assistant or the container. This is also where you can place the config.yaml file if you don't want all the sensors (see Installation).

Docker Environment Variables

A description of the Environment Variables available for this container. All of them have a default value, so you only need to add the onces where you want to change that.

Supported Languages

Currently these languages are supported for Wind Cardinals and other Text state strings:

If you would like to assist in translating to a new language, do the following:

Available Sensors

Here is the list of sensors that the program generates. Calculated Sensor means, if No, then data comes directly from the Weather Station, if yes, it is a sensor that is derived from some of the other sensors. For a copy ready list see further below

Sensor ID Name Description Calculated Sensor Default Units
absolute_humidity Absolute Humidity The amount of water per volume of air Yes g/m³
air_density Air Density The Air density Yes kg/m³
air_temperature Temperature Outside Temperature No
battery Battery The battery level on the sensor (If present) Yes %
battery_mode Battery Mode The battery operating mode on the TEMPEST unit (If present) Yes https://help.weatherflow.com/hc/en-us/articles/360048877194-Solar-Power-Rechargeable-Battery
beaufort Beaufort Scale Beaufort scale is an empirical measure that relates wind speed to observed conditions at sea or on land Yes #
cloud_base Cloud Base Altitude The estimated altitude above mean sea level (AMSL) to the cloud base Yes m
current_conditions Local Current Conditions The estimated current weather conditions derived from only local sensors in Home Assistant format Yes https://www.home-assistant.io/integrations/weather/
current_conditions_txt Local Current Conditions Text The estimated current weather conditions derived from only local sensors in human readable text Yes Clear Night, Cloudy, Fog, Hail, Lightning, Lightning & Rain, Partly Cloudy, Pouring Rain, Rain, Snow, Snow & Rain, Sunny, Windy, Wind & Rain, exceptional (not used)
delta_t Delta T Difference between Air Temperature and Wet Bulb Temperature Yes
dewpoint Dew Point Dewpoint in degrees Yes
dewpoint_description Dewpoint Comfort Level Textual representation of the Dewpoint value Yes
feelslike Feels Like Temperature The apparent temperature, a mix of Heat Index and Wind Chill Yes
fog_probability Fog Probability The probability of fog based on current conditions Yes %
freezing_level Freezing Level Altitude The estimated altitude above mean sea level (AMSL) where the temperature is at the freezing point (0°C/32°F) Yes m
illuminance Illuminance How much the incident light illuminates the surface No Lux
lightning_strike_count Lightning Count Number of lightning strikes in the last minute Yes #
lightning_strike_count_1hr Lightning Count (Last hour) Number of lightning strikes during the last hour Yes
lightning_strike_count_3hr Lightning Count (3 hours) Number of lightning strikes the last 3 hours Yes
lightning_strike_count_today Lightning Count (Today) Number of lightning strikes current day Yes
lightning_strike_distance Lightning Distance Distance of the last strike No km
lightning_strike_energy Lightning Energy Energy of the last strike No
lightning_strike_time Last Lightning Strike When the last lightning strike occurred Yes
precipitation_type Precipitation Type Can be one of None, Rain or Hail No 0 = none, 1 = rain, 2 = hail, 3 = rain + hail (heavy rain)
pressure_trend Pressure Trend Returns Steady, Falling or Rising determined by the rate of change over the past 3 hours Yes trend_text
rain_intensity Rain Intensity A descriptive text of how much is it raining right now Yes
rain_rate Rain Rate How much is it raining right now Yes mm/h
rain_start_time Last Rain When was the last time it rained No seconds
rain_today Rain Today Total rain for the current day. (Reset at midnight) Yes mm
rain_yesterday Rain Yesterday Total rain for yesterday (Reset at midnight) Yes mm
rain_duration_today Rain Duration (Today) Total rain minutes for the current day. (Reset at midnight) Yes minutes
rain_duration_yesterday Rain Duration (Yesterday) Total rain minutes yesterday Yes minutes
relative_humidity Humidity Relative Humidity No %
sealevel_pressure Station Pressure Preasure measurement at Sea Level Yes MB
snow_probability Snow Probability The probability of snow based on current conditions Yes %
status Status How long has the device been running and other HW details No
solar_elevation Solar Elevation Sun Elevation in Degrees with respect to the Horizon Yes ° (degree)
solar_insolation Solar Insolation Estimation of Solar Radiation at current sun elevation angle Yes W/m²
solar_radiation Solar Radiation Electromagnetic radiation emitted by the sun No W/m²
station_pressure Station Pressure Pressure measurement where the station is located No MB
status Status How long has the device been running and other HW details No Version Attribute returns the current version of this integration
temperature_description Temperature Level Textual representation of the Outside Air Temperature value Yes Text
uv UV Index The UV index No Index
uv_description UV Level Textual representation of the UV Index value Yes
visibility Visibility Distance to the horizon Yes km
voltage Voltage The voltage on the sensor (If present) No Volts
wetbulb Wet Bulb Temperature Temperature of a parcel of air cooled to saturation (100% relative humidity) Yes
wet_bulb_globe_temperature Wet Bulb Globe Temperature The WetBulb Globe Temperature (WBGT) is a measure of the heat stress in direct sunlight, which takes into account: temperature, humidity, wind speed, sun angle and cloud cover (solar radiation). Yes
wind_bearing Wind Bearing Current measured Wind bearing in degrees No Degrees
wind_bearing_avg Wind Bearing Avg The average wind bearing in degrees No Degrees
wind_direction Wind Direction Current measured Wind bearing as compass symbol Yes Cardinal
wind_direction_avg Wind Direction Avg The average wind direction as a compass string Yes Cardinal
wind_gust Wind Gust Highest wind speed for the last minute No m/s
wind_lull Wind Lull Lowest wind for the last minute No m/s
wind_speed Wind Speed Current measured Wind Speed No m/s
wind_speed_avg Wind Speed Avg Average wind speed for the last minute No m/s
weather Weather Only available if STATION_ID and STATION_TOKEN have valid data (See above). State will be current condition, and forecast data will be in the attributes. No
zambretti_number Zambretti Number Local Weather Forecast for the near future utilizing the Beteljuice Zambretti Algorhithm. Yes (0-25) number corresponds to Zambretti letters A-Z
zambretti_text Zambretti Text Local Weather Forecast for the near future utilizing the Beteljuice Zambretti Algorhithm. Yes Weather Forecast Text

Sensor Structure

See Available Sensors above for a description of each sensor.

sensors:
  - absolute_humidity
  - air_density
  - air_temperature
  - battery # voltage
  - battery_mode # support for Tempest devices only
  - beaufort
  - cloud_base
  - current_conditions
  - current_conditions_txt
  - delta_t
  - dewpoint
  - dewpoint_description
  - feelslike
  - fog_probability
  - freezing_level
  - illuminance
  - lightning_strike_count
  - lightning_strike_count_1hr
  - lightning_strike_count_3hr
  - lightning_strike_count_today
  - lightning_strike_distance
  - lightning_strike_energy
  - lightning_strike_time
  - precipitation_type
  - pressure_trend
  - rain_intensity
  - rain_rate
  - rain_start_time
  - rain_today
  - rain_yesterday
  - rain_duration_today
  - rain_duration_yesterday
  - relative_humidity
  - sealevel_pressure
  - snow_probability
  - solar_elevation
  - solar_insolation
  - solar_radiation
  - station_pressure
  - status
  - temperature_description
  - uv
  - uv_description
  - visibility
  - voltage
  - wbgt #Wet Bulb Globe Temperature
  - wetbulb
  - wind_bearing
  - wind_bearing_avg
  - wind_direction
  - wind_direction_avg
  - wind_gust
  - wind_lull
  - wind_speed
  - wind_speed_avg
  - weather
  - zambretti_number
  - zambretti_text

High and Low Values

For selected sensors high and low values are calculated and published to the attributes of the sensor. Currently daily, monthly and all-time values are calculated, but future values are planned. Only the sensors where it is relevant, will get a low value calculated. See the table further down, for the available sensors and what values to expect.

Here are the current attributes, that will be applied to the selected sensor:

Attribute Name Description
max_day Maximum value for the current day. Reset at midnight.
max_day_time UTC time when the max value was recorded. Reset at midnight.
min_day Minimum value for the current day. Reset at midnight.
min_day_time UTC time when the min value was recorded. Reset at midnight.
max_month Maximum value for the current month. Reset when new month.
max_month_time UTC time when the max value was recorded. Reset when new month.
min_month Minimum value for the current month. Reset when new month.
min_month_time UTC time when the min value was recorded. Reset when new month.
max_all Maximum value ever recorded. Updated at midnight every day.
max_all_time UTC time when the all-time max value was recorded. Updated at midnight every day.
min_all Minimum value ever recorded. Updated at midnight every day.
min_all_time UTC time when the all-time min value was recorded. Updated at midnight every day.

The following sensors are displaying High and Low values:

Sensor ID High Value Low Value
air_temperature Yes Yes
dewpoint Yes Yes
illuminance Yes No
lightning_strike_count_today Yes No
lightning_strike_energy Yes No
rain_rate Yes No
rain_duration_today Yes No
relative_humidity Yes Yes
sealevel_pressure Yes Yes
solar_radiation Yes No
uv Yes No
wind_gust Yes No
wind_lull Yes No
wind_speed_avg Yes No

Home Assistant Long Term Statistics

These sensors have long term statistics (LTS) enabled in Home Assistant (HA), no action by user is required to have LTS collected by HA this is done with MQTT autodiscovery. To display LTS in HA using the Statistics Graph Card (type: statistics-graph) the 'stat types' that can be used with this integration are Mean, Min, and Max. It is the user's discreation as to how to display the information, but cases such as rain today 'Max' would be a more logical selection without 'Mean' or 'Min'. During testing there has not been a use case for this integration that 'Sum' was of any valid use. Air, Sky, and Tempest sensors are specific to those units.

https://data.home-assistant.io/docs/statistics/

air_density
battery
beaufort
delta_t
dewpoint
feelslike
relative_humidity
illuminance
lightning_strike_count_today
lightning_strike_distance
lightning_strike_energy
rain_duration_today
rain_rate
rain_today
sealevel_pressure
solar_elevation
solar_insolation
solar_radiation
station_pressure
air_temperature
uv
visibility
voltage
wet_bulb_globe_temperature
wetbulb
wind_bearing
wind_bearing_avg
wind_gust
wind_lull
wind_speed
wind_speed_avg

Sensors in Developement

Local Current Conditions in Home Assistant format (Dev Branch)
Local Current Conditions in Human Readable Text (will need translations)
Probability of Snow (Dev Branch)
Probability of Fog (Dev Branch)

Creating a Home Assistant Weather Entity

If you have enabled the Forecast option, then there is a possibility to create a Weather Entity that can be used in all the different Lovelace Cards available for Weather. You can do this by using the Weather Template.

Edit configuration.yaml and insert the following (replacing hub_hb_00000001 and tempest_st_00000001 with the appropriate ids of your sensors):

weather:
  - platform: template
    name: My Local Weather
    condition_template: "{{ states('sensor.hub_hb_00000001_weather') }}"
    # condition_template: "{{ states('tempest_st_00000001_current_conditions') }}" # Local Only Option
    temperature_template: "{{ states('sensor.tempest_st_00000001_temperature') | float}}"
    humidity_template: "{{ states('sensor.tempest_st_00000001_humidity')| int }}"
    pressure_template: "{{ states('sensor.tempest_st_00000001_sea_level_pressure')| float }}"
    wind_speed_template: "{{ ( states('sensor.tempest_st_00000001_wind_speed_avg') | float * 18 / 5 ) | round(2) }}"
    wind_bearing_template: "{{ states('sensor.tempest_st_00000001_wind_bearing_avg')| int }}"
    visibility_template: "{{ states('sensor.tempest_st_00000001_visibility')| float }}"
    forecast_template: "{{ state_attr('sensor.hub_hb_00000001_weather', 'hourly_forecast') }}"

Setup Dev environment

virtualenv -p `which python3` env
source env/bin/activate
python setup.py install

Then you just need to export the configuration

export TZ="America/Toronto"
export UNIT_SYSTEM="metric"
export LANGUAGE="en"
export RAPID_WIND_INTERVAL="0"
export DEBUG="True"
export EXTERNAL_DIRECTORY="."
export ELEVATION="30"
export WF_HOST="0.0.0.0"
export WF_PORT="50222"
export MQTT_HOST="..."
export MQTT_PORT="1883"
export MQTT_DEBUG="False"
export STATION_ID="..."
export STATION_TOKEN="..."
export FORECAST_INTERVAL="30"
export MQTT_USERNAME="..."
export MQTT_PASSWORD="..."

Then you can run the daemon with

weatherflow2mqtt