Skip to content

Home Assistant ​

The ha-njord custom integration connects Home Assistant to njord via gRPC. Data flows in real time through gRPC streams, so entities update as soon as njord processes a new poll cycle. There is no polling delay on the HA side.

Installation ​

  1. Open HACS, then go to three dots > Custom repositories
  2. Add https://github.com/st0o0/ha-njord as Integration
  3. Search for njord Weather and install
  4. Restart Home Assistant

Manual ​

Copy the custom_components/njord directory into your Home Assistant config/custom_components/ folder and restart.

Setup ​

  1. Go to Settings > Devices & Services > Add Integration
  2. Search for njord Weather
  3. Enter the host and gRPC port of your njord instance (default port: 8081)
  4. The integration auto-discovers all configured locations and models

Device structure ​

The integration creates two types of devices:

Location device (one per configured location, e.g. "njord Home"):

  • Weather entities for each model and the consensus
  • Enrichment sensors (alerts, indices, trends, derived, history)
  • Weather alert event entity
  • Inversion binary sensor

Server device (one per njord instance, e.g. "njord Server"):

  • Trigger Poll button
  • Stream connectivity sensors (forecast, enrichment, config)
  • API usage sensors (monthly, daily)
  • Version and uptime sensors
  • Per-target poll state sensors

Find all njord devices under Settings > Devices & Services > njord Weather.

Entity reference ​

Weather (weather.*) ​

Each location/model combination creates a weather entity. An additional consensus entity aggregates all models per location.

EntityExample
Per modelweather.njord_home_icon_d2
Consensusweather.njord_home_consensus

State attributes (current conditions):

AttributeUnitSource
statecondition stringWMO weather code mapped to HA condition (sunny, cloudy, rainy, etc.)
temperature°CAir temperature at 2m
apparent_temperature°CFeels-like temperature
humidity%Relative humidity at 2m
pressurehPaMean sea level pressure
wind_speedm/sWind speed at 10m
wind_bearing°Wind direction (0=N, 90=E, 180=S, 270=W)
cloud_cover%Total cloud cover

Model info attributes (on per-model entities):

AttributeDescription
model_display_nameHuman-readable model name
model_providerWeather service provider
model_regionGeographic coverage area
model_coverage_tierCoverage classification
model_resolution_kmGrid resolution in km
model_max_forecast_hoursMaximum forecast horizon

When the history enrichment is active, per-model entities also carry model_mae_7d, model_mae_30d, model_weight, and model_drift.

Consensus extra attributes:

AttributeDescription
agreementFraction of models agreeing on temperature direction (0 to 1)
available_modelsNumber of models contributing
spreadTemperature spread between models in °C
reliable_hoursHours where model agreement stays above 50%
current_horizonWhich horizon offset is currently displayed (e.g. h3)

Forecasts are available via the weather.get_forecasts service with type: hourly or type: daily. Extra forecast parameters configured in njord (e.g. cape, uv_index) appear as additional fields in the forecast entries.


Alert sensors (sensor.*_alert) ​

14 alert types, each showing the actual trigger value as state. Disabled by default.

Alert TypeEntity suffixUnitWhat it measures
Frostfrost_alert°CMinimum forecast temperature
Heatheat_alert°CMaximum forecast temperature
Stormstorm_alertm/sMaximum wind gust speed
Heavy Rainheavy_rain_alertmmPrecipitation amount
UVuv_alertUVMaximum UV index
Fogfog_alertmMinimum visibility
Snowsnow_alertcmSnowfall depth
Pressure Droppressure_drop_alerthPaPressure change (3h)
Thunderstormthunderstorm_alertm/sWind gusts during thunderstorm
Iceice_alert°CSurface temperature near freezing
Wind Chillwind_chill_alert°CPerceived cold temperature
Visibilityvisibility_alertmLow visibility distance
Tropical Nighttropical_night_alert°CMinimum nighttime temperature
Humidityhumidity_alert%Extreme humidity levels

Entity ID pattern: sensor.njord_{location}_{type}_alert (e.g. sensor.njord_home_frost_alert)

State is None when no alert data is available. The trigger value (e.g. -2.1 °C for frost) is shown when an alert condition exists.

Attributes:

AttributeTypeDescription
severitystringAlert level: none, yellow, orange, red
confidencefloatCertainty (0 to 1)
thresholdfloatConfigured threshold for this alert type
peak_valuefloatMaximum forecast value if higher than current (only when set)
hours_untilintHours until the condition occurs (only when set)
duration_hoursintExpected duration in hours (only when set)

Activity indices (sensor.*_index) ​

8 activity scores (0 to 100%) indicating weather suitability. Disabled by default.

EntityIconWhat it measures
sensor.njord_{loc}_laundry_indextshirtOutdoor laundry drying conditions
sensor.njord_{loc}_outdoor_indexpine-treeGeneral outdoor comfort
sensor.njord_{loc}_running_indexrunRunning conditions
sensor.njord_{loc}_cycling_indexbikeCycling conditions
sensor.njord_{loc}_bbq_indexgrillBarbecue-friendliness
sensor.njord_{loc}_irrigation_indexsprinklerGarden irrigation need
sensor.njord_{loc}_solar_indexsolar-powerSolar energy production potential
sensor.njord_{loc}_night_ventilation_indexair-filterNight ventilation benefit

Each index sensor carries a forecast attribute with an array of {day_offset, score} entries for multi-day outlook.


Additional sensors ​

All disabled by default. Enable via the entity registry.

Frost ​

EntityUnitDescription
sensor.njord_{loc}_frost_hourshForecast hours with temperature below 0 °C
sensor.njord_{loc}_frost_confidence%Confidence (0 to 100%) that frost will occur

VPD (Vapour Pressure Deficit) ​

EntityUnitDescription
sensor.njord_{loc}_vpdkPaDrying power of the air. Attribute: category (low, optimal, high, critical)

Weather trend ​

EntityDescription
sensor.njord_{loc}_weather_trendWeather change description (e.g. "clearing skies", "rain approaching")

Attributes: stability_label, precip_starts_in_hours, precip_ends_in_hours, temp_max_in_hours, temp_min_in_hours, reliable_hours, stability_ratio, decay_rate, parameter_trends

Derived metrics ​

EntityUnitDescription
sensor.njord_{loc}_sunshine%Sunshine percentage based on cloud cover
sensor.njord_{loc}_diurnal_amplitude°CDaily max/min temperature difference
sensor.njord_{loc}_beaufort0 to 12Wind on the Beaufort scale
sensor.njord_{loc}_wind_chill°CPerceived temperature factoring wind
sensor.njord_{loc}_dewpoint_comfortstringComfort category based on dew point (e.g. "Comfortable", "Humid")

Model performance (diagnostic) ​

EntityUnitDescription
sensor.njord_{loc}_model_performance°CAccuracy-weighted ensemble temperature

Attributes: models (array of {model, mae_7d, mae_30d, weight, drift}), seasonal_best, anomaly, anomaly_deviation


Diagnostic sensors (server device) ​

EntityUnitDescription
sensor.njord_monthly_usage%Monthly API budget usage
sensor.njord_daily_usage%Daily API budget usage
sensor.njord_versionstringnjord server version
sensor.njord_uptimehServer uptime

Each usage sensor carries limit and used attributes.

Target sensors (disabled by default): sensor.njord_{location}_{model}_target shows the next poll time for each location/model pair, with attributes phase, miss_count, last_change, cycle_seconds.


Binary sensors (binary_sensor.*) ​

EntityDefaultDescription
binary_sensor.njord_{loc}_inversiondisabledTemperature inversion detection (warm air above cold)
binary_sensor.njord_forecast_streamenabledgRPC forecast stream connectivity (diagnostic)
binary_sensor.njord_enrichment_streamenabledgRPC enrichment stream connectivity (diagnostic)
binary_sensor.njord_config_streamenabledgRPC config stream connectivity (diagnostic)

Event entity (event.*) ​

One event entity per location fires on weather alert state changes.

Entity ID: event.njord_{location}_weather_alert

Event typeWhen it fires
alert_startedA new alert activates
alert_escalatedAn active alert increases in severity
alert_deescalatedAn active alert decreases in severity
alert_clearedAn alert is no longer active

Event data: type, location, severity, confidence, trigger_value, threshold, peak_value, hours_until, duration_hours, previous_severity (on escalation/deescalation/cleared)


Button (button.*) ​

EntityDescription
button.njord_trigger_pollTriggers an immediate poll cycle on the njord server

Attributes after pressing: triggered_count, last_triggered.


Enabling disabled entities ​

Many enrichment sensors are disabled by default to keep the entity list manageable. To enable them:

  1. Go to Settings > Devices & Services > njord Weather
  2. Click the location device
  3. Find the entity you want, click it
  4. Toggle Enabled on

Alternatively, use Settings > Entities, filter by "njord", and bulk-enable the sensors you need.

Recorder exclude ​

The integration can create many entities per location (40+ with all enrichments enabled). To prevent your Home Assistant database from growing rapidly, add a recorder exclude:

yaml
# configuration.yaml
recorder:
  exclude:
    entity_globs:
      - sensor.njord_*
      - binary_sensor.njord_*

TIP

This excludes njord sensors from the long-term history database while keeping them fully functional for automations, dashboards, and current state display. If you want history for specific sensors, use an include override for those.

Dashboard examples ​

Weather forecast card ​

Use the built-in weather forecast card with any njord weather entity:

yaml
type: weather-forecast
entity: weather.njord_home_consensus
forecast_type: daily

Multi-model comparison ​

Compare forecasts across models using a weather forecast card per model, or use an entities card to compare attributes:

yaml
type: entities
title: Current Temperature by Model
entities:
  - entity: weather.njord_home_icon_d2
    name: ICON-D2
  - entity: weather.njord_home_icon_eu
    name: ICON-EU
  - entity: weather.njord_home_ecmwf_ifs025
    name: ECMWF
  - entity: weather.njord_home_consensus
    name: Consensus

Weather alerts overview ​

yaml
type: entities
title: Weather Alerts
entities:
  - entity: sensor.njord_home_frost_alert
    name: Frost
  - entity: sensor.njord_home_heat_alert
    name: Heat
  - entity: sensor.njord_home_storm_alert
    name: Storm
  - entity: sensor.njord_home_uv_alert
    name: UV
  - entity: sensor.njord_home_thunderstorm_alert
    name: Thunderstorm

Activity indices ​

yaml
type: entities
title: Activity Scores
entities:
  - entity: sensor.njord_home_outdoor_index
    name: Outdoor
  - entity: sensor.njord_home_running_index
    name: Running
  - entity: sensor.njord_home_cycling_index
    name: Cycling
  - entity: sensor.njord_home_bbq_index
    name: BBQ
  - entity: sensor.njord_home_solar_index
    name: Solar

Automation examples ​

Frost warning using the event entity ​

The event entity fires whenever an alert changes state, making it ideal for notifications:

yaml
automation:
  - alias: "Frost warning notification"
    trigger:
      - platform: event
        event_type: state_changed
        event_data:
          entity_id: event.njord_home_weather_alert
    condition:
      - condition: template
        value_template: >
          {{ trigger.event.data.new_state.attributes.event_type == 'alert_started'
             and trigger.event.data.new_state.attributes.type == 'frost' }}
    action:
      - action: notify.mobile_app
        data:
          title: "Frost Warning"
          message: >
            Frost expected in {{ trigger.event.data.new_state.attributes.hours_until }} hours.
            Trigger value: {{ trigger.event.data.new_state.attributes.trigger_value }} °C

Trigger a poll on demand ​

Use the button entity in an automation or call it from the UI:

yaml
automation:
  - alias: "Poll njord before sunrise"
    trigger:
      - platform: sun
        event: sunrise
        offset: "-01:00:00"
    action:
      - action: button.press
        target:
          entity_id: button.njord_trigger_poll

Entity availability ​

Entities become unavailable when:

  • The gRPC connection to njord is lost (the stream connectivity binary sensors turn off)
  • njord has no data for a location or model
  • An enrichment feature is disabled in the njord configuration

The three stream connectivity sensors (binary_sensor.njord_*_stream) show the real-time connection state. If all three are off, the integration cannot reach the njord server.

Open-Meteo data is licensed under CC BY 4.0.