venus/dbus-tides/config.py

"""
Configuration for dbus-tides Venus OS service.

All tunable parameters in one place for easy adjustment.
"""

# =============================================================================
# D-BUS SERVICE CONFIGURATION
# =============================================================================

SERVICE_NAME = 'com.victronenergy.tides'

# =============================================================================
# DEPTH SAMPLING
# =============================================================================

# How often to read the depth sensor (seconds)
DEPTH_SAMPLE_INTERVAL = 10

# Window for averaging raw depth readings to smooth wave noise (seconds)
DEPTH_AVG_WINDOW = 300  # 5 minutes

# How many hours of 5-min averages to keep in the ring buffer and DB
DEPTH_HISTORY_HOURS = 96

# Median filter kernel size (number of 5-min samples).  Odd integer.
# Removes impulse noise from anchor swing without shifting timing.
MEDIAN_FILTER_KERNEL = 5

# Window for smoothing the 5-min averages for trend/slope detection (seconds).
# Triangular-weighted moving average; wider than the raw averaging window to
# suppress anchor-swing residuals that survive the 5-min mean.
SMOOTHING_WINDOW = 3600  # 60 minutes

# =============================================================================
# TIDE DETECTION
# =============================================================================

# Minimum depth change (meters) between consecutive high/low events.
# Must exceed the peak-to-peak residual noise in the smoothed curve.
MIN_TIDE_AMPLITUDE = 0.4

# Depth excursion (meters) required after a candidate extremum before it is
# reported.  In calm conditions the smoothed curve moves away quickly; in
# noisy conditions (anchor swing) confirmation is naturally delayed until
# enough data accumulates to fit an unambiguous trend.
TIDE_CONFIRMATION_DEPTH = 0.2

# =============================================================================
# SPEED GATE
# =============================================================================

# Maximum vessel speed (m/s) to accept depth readings.
# 2 knots = 1.02889 m/s
SPEED_THRESHOLD_MS = 1.03

# =============================================================================
# LOCATION THRESHOLDS
# =============================================================================

# How often to sample GPS for position tracking (seconds)
GPS_SAMPLE_INTERVAL = 60

# GPS history buffer size for movement detection
GPS_HISTORY_SIZE = 4

# GPS history sample interval (seconds)
GPS_HISTORY_SAMPLE_INTERVAL = 900  # 15 minutes

# Within this radius (meters), tidal timing is considered consistent.
# Depth observations remain valid for the same anchorage.
# 5 nautical miles = 9260 meters
STATIONARY_RADIUS_METERS = 9260

# When the vessel moves more than this distance (meters), recalibrate
# chart_depth using only recent observations from the new position.
# Tidal correction factors (Dt, k) are preserved since the tidal
# characteristics are unchanged within the stationary radius.
# 500 feet = 152.4 meters
CHART_DEPTH_RECAL_METERS = 152.4

# Beyond this radius (meters), re-interpolate tidal constituents from grid.
# 20 nautical miles = 37040 meters
MODEL_RERUN_RADIUS_METERS = 37040

# Maximum time between tide predictions (seconds) even if stationary
MODEL_RERUN_INTERVAL = 86400  # 1 day

# =============================================================================
# LOCAL ADAPTATION
# =============================================================================

# Maximum time difference (seconds) to match an observed event to a predicted
# extremum.  3 hours accommodates large coastal propagation delays.
ADAPTATION_MAX_MATCH_WINDOW = 10800

# Minimum number of matched observed/predicted pairs before applying a
# timing correction.
ADAPTATION_MIN_MATCHES = 2

# Minimum number of high+low range pairs before computing amplitude scaling.
ADAPTATION_MIN_RANGE_PAIRS = 1

# Smoothing kernel width (seconds) for the observation-vs-prediction residual.
# Must be wide enough to filter 5-min noise but narrow enough to preserve
# tidal shape (~1.5 hours).
RESIDUAL_SMOOTHING_WINDOW = 5400  # 1.5 hours

# Exponential decay half-life (hours) for extrapolating the residual
# correction beyond the last observation into the future.
RESIDUAL_DECAY_HOURS = 6

# =============================================================================
# TIDE PREDICTION
# =============================================================================

# How many hours ahead to predict
PREDICTION_HOURS = 48

# Time step for the predicted tide curve (seconds)
PREDICTION_INTERVAL = 900  # 15-minute intervals

# =============================================================================
# PATH CONFIGURATION
# =============================================================================

DATA_DIR = '/data/dbus-tides'
DB_FILE = DATA_DIR + '/depth_history.db'
CONSTITUENTS_DIR = DATA_DIR + '/constituents'
GRID_FILE_NAME = 'coastal_grid.json.gz'
NOAA_STATIONS_FILE_NAME = 'noaa_stations.json.gz'

# Maximum distance (meters) to a NOAA station for it to be used.
# Observation-derived constituents are preferred over the global model
# when the vessel is within this radius of a station.
# 50 nautical miles = 92600 meters
NOAA_STATION_MAX_DISTANCE = 92600

# Number of nearby NOAA stations to report for UI selection
NOAA_NEARBY_COUNT = 5

# Minimum hours of depth history required before attempting
# best-fit station scoring against observed data
BESTFIT_MIN_HISTORY_HOURS = 12

# =============================================================================
# LOGGING CONFIGURATION
# =============================================================================

LOGGING_CONFIG = {
    'level': 'INFO',
    'console': True,
    'include_timestamp': False,
}

VERSION = '1.0.20'