venus/dbus-meteoblue-forecast/README.md

Meteoblue Forecast for Venus OS

Fetches 7-day weather forecasts from the Meteoblue Forecast API and publishes them on D-Bus for display in the venus-html5-app dashboard.

Features

• 7-day forecast: wind speed, gusts, direction, precipitation, and waves
• Single API call combining basic, wind, and sea packages
• Automatic GPS position from Venus OS D-Bus
• Movement-aware refresh: 6 hours (stationary) / 3 hours (moving)
• Settings via MQTT or config file
• Persists across restarts and firmware updates

Prerequisites

• Venus OS device (Cerbo GX, Venus GX, Raspberry Pi)
• GPS source connected to Venus OS
• Meteoblue API key (register here)

Installation

1. Copy the package to the Venus OS device:

   scp -r dbus-meteoblue-forecast root@<venus-ip>:/data/
   

2. SSH into the device and install:

   ssh root@<venus-ip>
   chmod +x /data/dbus-meteoblue-forecast/install.sh
   /data/dbus-meteoblue-forecast/install.sh
   

3. Configure your API key:

   vi /data/dbus-meteoblue-forecast/forecast_config.json
   

   Set "api_key" to your Meteoblue API key.

Configuration

Config file (recommended for initial setup)

Edit /data/dbus-meteoblue-forecast/forecast_config.json:

{
    "api_key": "your-meteoblue-api-key"
}

MQTT

Publish to W/<vrm-id>/meteoblueforecast/0/Settings/ApiKey with {"value": "your-key"}.

D-Bus / MQTT Paths

Path	Type	R/W	Description
/Connected	int	R	1 when service is running
/Status	int	R	0=Idle, 1=Fetching, 2=Ready, 3=Error
/ErrorMessage	string	R	Last error description
/LastUpdate	int	R	Unix timestamp of last fetch
/NextUpdate	int	R	Unix timestamp of next fetch
/IsMoving	int	R	0=stationary, 1=moving
/Forecast/Latitude	float	R	Latitude used for forecast
/Forecast/Longitude	float	R	Longitude used for forecast
/Forecast/Json	string	R	JSON blob with forecast arrays
/Settings/Enabled	int	W	0=disabled, 1=enabled
/Settings/ApiKey	string	W	Meteoblue API key
/Settings/Units	int	W	0=Metric, 1=Imperial

Forecast JSON Structure

The /Forecast/Json path contains a JSON string with the following arrays:

{
    "ts": [1740268800000, ...],
    "windspeed": [5.2, ...],
    "winddirection": [180, ...],
    "gust": [8.2, ...],
    "precip": [0.0, ...],
    "waves_height": [1.2, ...],
    "waves_period": [6.0, ...],
    "waves_direction": [180, ...]
}

• ts: Timestamps in milliseconds since epoch (UTC)
• windspeed: Wind speed in m/s (10m above ground)
• winddirection: Wind direction in degrees
• gust: Wind gust speed in m/s
• precip: Hourly precipitation in mm
• waves_height: Significant wave height in meters
• waves_period: Mean wave period in seconds
• waves_direction: Mean wave direction in degrees

Wind speed in knots = windspeed * 1.94384

Service Management

# Check status
svstat /service/dbus-meteoblue-forecast

# View logs
tail -F /var/log/dbus-meteoblue-forecast/current | tai64nlocal

# Restart service
svc -t /service/dbus-meteoblue-forecast

# Stop service
svc -d /service/dbus-meteoblue-forecast

Uninstall

chmod +x /data/dbus-meteoblue-forecast/uninstall.sh
/data/dbus-meteoblue-forecast/uninstall.sh

API Details

Uses the Meteoblue Forecast API:

• Endpoint: GET https://my.meteoblue.com/packages/basic-1h_wind-1h_sea-1h
• basic-1h: windspeed, winddirection, precipitation (hourly, 7-day)
• wind-1h: windgusts (hourly, 7-day)
• sea-1h: wave height, period, direction (hourly, valid 20km+ offshore)
• Rate limit: 500 calls/minute (default)