farsounder 0.1.0__py3-none-any.whl

farsounder/__init__.py

@@ -0,0 +1,5 @@
+from farsounder.client import config as config
+from farsounder.client import requests as requests
+from farsounder.client import subscriber as subscriber
+from farsounder.client import exceptions as exceptions
+from farsounder.proto import proto as proto

farsounder/client/config.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Literal, Mapping
+
+PubSubMessage = Literal[
+    "HydrophoneData",
+    "TargetData",
+    "ProcessorSettings",
+    "VesselInfo",
+]
+
+ReqRepEndpoint = Literal[
+    "GetProcessorSettings",
+    "SetFieldOfView",
+    "SetBottomDetection",
+    "SetInWaterSquelch",
+    "SetSquelchlessInWaterDetector",
+    "GetVesselInfo",
+    "SetDraft",
+    "SetKeelOffset",
+]
+
+RestEndpoint = Literal["GetHistoryData",]
+
+PUBSUB_DEFAULT_PORTS: dict[PubSubMessage, int] = {
+    "HydrophoneData": 61501,
+    "TargetData": 61502,
+    "ProcessorSettings": 61503,
+    "VesselInfo": 61504,
+}
+
+REQREP_DEFAULT_PORTS: dict[ReqRepEndpoint, int] = {
+    "GetProcessorSettings": 60501,
+    "SetFieldOfView": 60502,
+    "SetBottomDetection": 60503,
+    "SetInWaterSquelch": 60504,
+    "SetSquelchlessInWaterDetector": 60505,
+    "GetVesselInfo": 60506,
+    "SetDraft": 60507,
+    "SetKeelOffset": 60508,
+}
+
+REST_DEFAULT_PORTS: dict[RestEndpoint, int] = {
+    "GetHistoryData": 3000,
+}
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Configuration for the ZeroMQ client.
+
+    Parameters
+    ----------
+    host
+        Hostname or IP address for all sockets.
+    subscribe
+        Pub-sub message types to subscribe to.
+    pubsub_ports
+        Port mapping for pub-sub message types.
+    reqrep_ports
+        Port mapping for request-reply endpoints.
+    rest_ports
+        Port mapping for REST endpoints.
+    callback_executor
+        Whether to run sync callbacks in a thread pool or inline.
+    timeout_seconds
+        Request-reply timeout in seconds.
+    """
+
+    host: str
+    subscribe: tuple[PubSubMessage, ...]
+    pubsub_ports: dict[PubSubMessage, int]
+    reqrep_ports: dict[ReqRepEndpoint, int]
+    rest_ports: dict[RestEndpoint, int]
+    callback_executor: Literal["threadpool", "inline"]
+    timeout_seconds: float
+
+
+def build_config(
+    host: str = "127.0.0.1",
+    subscribe: Iterable[PubSubMessage] | None = None,
+    port_overrides: Mapping[str, int] | None = None,
+    callback_executor: Literal["threadpool", "inline"] = "threadpool",
+    timeout_seconds: float = 2.0,
+) -> ClientConfig:
+    """Build a client configuration.
+
+    Parameters
+    ----------
+    host
+        Hostname or IP address for all sockets.
+    subscribe
+        Iterable of message types to subscribe to. Defaults to all pub-sub
+        messages.
+    port_overrides
+        Mapping of message or endpoint name to port number. Keys can be any
+        pub-sub message name, request-reply endpoint name, or REST endpoint
+        name such as GetHistoryData.
+    callback_executor
+        Whether to run sync callbacks in a thread pool or inline.
+    timeout_seconds
+        Request-reply timeout in seconds.
+
+    Returns
+    -------
+    ClientConfig
+        The constructed configuration.
+    """
+
+    pubsub_ports = dict(PUBSUB_DEFAULT_PORTS)
+    reqrep_ports = dict(REQREP_DEFAULT_PORTS)
+    rest_ports = dict(REST_DEFAULT_PORTS)
+
+    if port_overrides:
+        for key, port in port_overrides.items():
+            if key in pubsub_ports:
+                pubsub_ports[key] = port
+            elif key in reqrep_ports:
+                reqrep_ports[key] = port
+            elif key in rest_ports:
+                rest_ports[key] = port
+            else:
+                raise ValueError(f"Unknown port override key: {key}")
+
+    subscribe_list = tuple(subscribe) if subscribe is not None else tuple(pubsub_ports)
+    for message_type in subscribe_list:
+        if message_type not in pubsub_ports:
+            raise ValueError(f"Unknown pub-sub message type: {message_type}")
+
+    return ClientConfig(
+        host=host,
+        subscribe=subscribe_list,
+        pubsub_ports=pubsub_ports,
+        reqrep_ports=reqrep_ports,
+        rest_ports=rest_ports,
+        callback_executor=callback_executor,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def resolve_pubsub_port(config: ClientConfig, message_type: PubSubMessage) -> int:
+    """Resolve the port for a pub-sub message type."""
+
+    return config.pubsub_ports[message_type]
+
+
+def resolve_reqrep_port(config: ClientConfig, endpoint: ReqRepEndpoint) -> int:
+    """Resolve the port for a request-reply endpoint."""
+
+    return config.reqrep_ports[endpoint]
+
+
+def resolve_rest_port(config: ClientConfig, endpoint: RestEndpoint) -> int:
+    """Resolve the port for a REST endpoint."""
+
+    return config.rest_ports[endpoint]

farsounder/client/exceptions.py

@@ -0,0 +1,2 @@
+class RequestTimeoutError(TimeoutError):
+    """Request-reply operation timed out."""

farsounder/client/history_types.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class GriddedBottomDetection:
+    timestamp_utc: float
+    latitude_degrees: float
+    longitude_degrees: float
+    grid_interval_meters: float
+    target_strength_db: float
+    is_tide_corrected: bool
+    uploaded_to_cloud: bool
+    number_of_points: int
+    depth_meters: float
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GriddedBottomDetection":
+        return cls(
+            timestamp_utc=float(data["timestamp_utc"]),
+            latitude_degrees=float(data["latitude_degrees"]),
+            longitude_degrees=float(data["longitude_degrees"]),
+            grid_interval_meters=float(data["grid_interval_meters"]),
+            target_strength_db=float(data["target_strength_db"]),
+            is_tide_corrected=bool(data["is_tide_corrected"]),
+            uploaded_to_cloud=bool(data["uploaded_to_cloud"]),
+            number_of_points=int(data["number_of_points"]),
+            depth_meters=float(data["depth_meters"]),
+        )
+
+
+@dataclass(frozen=True)
+class GriddedInwaterDetection:
+    timestamp_utc: float
+    latitude_degrees: float
+    longitude_degrees: float
+    grid_interval_meters: float
+    target_strength_db: float
+    is_tide_corrected: bool
+    uploaded_to_cloud: bool
+    number_of_points: int
+    deepest_depth_meters: float | None
+    shallowest_depth_meters: float | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GriddedInwaterDetection":
+        return cls(
+            timestamp_utc=float(data["timestamp_utc"]),
+            latitude_degrees=float(data["latitude_degrees"]),
+            longitude_degrees=float(data["longitude_degrees"]),
+            grid_interval_meters=float(data["grid_interval_meters"]),
+            target_strength_db=float(data["target_strength_db"]),
+            is_tide_corrected=bool(data["is_tide_corrected"]),
+            uploaded_to_cloud=bool(data["uploaded_to_cloud"]),
+            number_of_points=int(data["number_of_points"]),
+            deepest_depth_meters=(
+                float(data["deepest_depth_meters"])
+                if data.get("deepest_depth_meters") is not None
+                else None
+            ),
+            shallowest_depth_meters=(
+                float(data["shallowest_depth_meters"])
+                if data.get("shallowest_depth_meters") is not None
+                else None
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class HistoryData:
+    gridded_bottom_detections: list[GriddedBottomDetection]
+    gridded_inwater_detections: list[GriddedInwaterDetection]
+    history_count: int | None = None
+
+    @classmethod
+    def from_dict(
+        cls, data: dict[str, Any], *, history_count: int | None = None
+    ) -> "HistoryData":
+        bottom_raw = data.get("gridded_bottom_detections", [])
+        inwater_raw = data.get("gridded_inwater_detections", [])
+        return cls(
+            gridded_bottom_detections=[
+                GriddedBottomDetection.from_dict(item) for item in bottom_raw
+            ],
+            gridded_inwater_detections=[
+                GriddedInwaterDetection.from_dict(item) for item in inwater_raw
+            ],
+            history_count=history_count,
+        )

farsounder/client/requests.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TypeVar
+
+import httpx
+import zmq
+import zmq.asyncio
+from google.protobuf.message import Message
+
+from farsounder.proto.proto import nav_api_pb2 as nav_api
+from farsounder.client.config import (
+    ClientConfig,
+    ReqRepEndpoint,
+    resolve_reqrep_port,
+    resolve_rest_port,
+)
+from farsounder.client.exceptions import RequestTimeoutError
+from farsounder.client.history_types import HistoryData
+
+ResponseT = TypeVar("ResponseT", bound=Message)
+
+
+async def _request(
+    config: ClientConfig,
+    endpoint: ReqRepEndpoint,
+    request: Message,
+    response_cls: type[ResponseT],
+) -> ResponseT:
+    ctx = zmq.asyncio.Context.instance()
+    socket = ctx.socket(zmq.REQ)
+    try:
+        port = resolve_reqrep_port(config, endpoint)
+        socket.connect(f"tcp://{config.host}:{port}")
+        await socket.send(request.SerializeToString())
+        try:
+            data = await asyncio.wait_for(socket.recv(), timeout=config.timeout_seconds)
+        except asyncio.TimeoutError as exc:
+            raise RequestTimeoutError(
+                f"Timeout waiting for {endpoint} after {config.timeout_seconds:.1f}s"
+            ) from exc
+    finally:
+        socket.close(linger=0)
+
+    response = response_cls()
+    response.ParseFromString(data)
+    return response
+
+
+async def get_processor_settings(
+    config: ClientConfig,
+) -> nav_api.GetProcessorSettingsResponse:
+    """Request the current processor settings.
+
+    Parameters
+    ----------
+    config
+        Client configuration.
+
+    Returns
+    -------
+    nav_api.GetProcessorSettingsResponse
+        Response containing the current processor settings.
+    """
+
+    request = nav_api.GetProcessorSettingsRequest()
+    return await _request(
+        config,
+        "GetProcessorSettings",
+        request,
+        nav_api.GetProcessorSettingsResponse,
+    )
+
+
+async def set_field_of_view(
+    fov: nav_api.FieldOfView,
+    config: ClientConfig,
+) -> nav_api.SetFieldOfViewResponse:
+    """Request a change to the sonar FieldOfView.
+
+    Parameters
+    ----------
+    fov
+        Desired field of view value.
+    config
+        Client configuration.
+
+    Returns
+    -------
+    nav_api.SetFieldOfViewResponse
+        Response describing the result of the request.
+    """
+
+    request = nav_api.SetFieldOfViewRequest(fov=fov)
+    return await _request(
+        config,
+        "SetFieldOfView",
+        request,
+        nav_api.SetFieldOfViewResponse,
+    )
+
+
+async def set_bottom_detection(
+    enable: bool,
+    config: ClientConfig,
+) -> nav_api.SetBottomDetectionResponse:
+    """Enable or disable bottom detection.
+
+    Parameters
+    ----------
+    enable
+        Whether to enable bottom detection.
+    config
+        Client configuration.
+
+    Returns
+    -------
+    nav_api.SetBottomDetectionResponse
+        Response describing the result of the request.
+    """
+
+    request = nav_api.SetBottomDetectionRequest(enable_bottom_detection=enable)
+    return await _request(
+        config,
+        "SetBottomDetection",
+        request,
+        nav_api.SetBottomDetectionResponse,
+    )
+
+
+async def set_inwater_squelch(
+    value: float,
+    config: ClientConfig,
+) -> nav_api.SetInWaterSquelchResponse:
+    """Set the in-water squelch value.
+
+    Parameters
+    ----------
+    value
+        Squelch value to set.
+    config
+        Client configuration.
+
+    Returns
+    -------
+    nav_api.SetInWaterSquelchResponse
+        Response describing the result of the request.
+    """
+
+    request = nav_api.SetInWaterSquelchRequest(new_squelch_val=value)
+    return await _request(
+        config,
+        "SetInWaterSquelch",
+        request,
+        nav_api.SetInWaterSquelchResponse,
+    )
+
+
+async def set_squelchless_inwater_detector(
+    enable: bool,
+    config: ClientConfig,
+) -> nav_api.SetSquelchlessInWaterDetectorResponse:
+    """Enable or disable the squelchless in-water detector.
+
+    Parameters
+    ----------
+    enable
+        Whether to enable squelchless detection.
+    config
+        Client configuration.
+
+    Returns
+    -------
+    nav_api.SetSquelchlessInWaterDetectorResponse
+        Response describing the result of the request.
+    """
+
+    request = nav_api.SetSquelchlessInWaterDetectorRequest(
+        enable_squelchless_detection=enable
+    )
+    return await _request(
+        config,
+        "SetSquelchlessInWaterDetector",
+        request,
+        nav_api.SetSquelchlessInWaterDetectorResponse,
+    )
+
+
+async def get_vessel_info(
+    config: ClientConfig,
+) -> nav_api.GetVesselInfoResponse:
+    """Request the current vessel info.
+
+    Parameters
+    ----------
+    config
+        Client configuration.
+
+    Returns
+    -------
+    nav_api.GetVesselInfoResponse
+        Response containing the vessel info.
+    """
+
+    request = nav_api.GetVesselInfoRequest()
+    return await _request(
+        config, "GetVesselInfo", request, nav_api.GetVesselInfoResponse
+    )
+
+
+def _build_history_params(
+    *,
+    latitude: float,
+    longitude: float,
+    radius_meters: float,
+    since_timestamp_utc: float | None,
+    tide_corrected_only: bool,
+    skip: int,
+    limit: int,
+    include_count: bool,
+) -> dict[str, str]:
+    params: dict[str, str] = {
+        "latitude": str(latitude),
+        "longitude": str(longitude),
+        "radius_meters": str(radius_meters),
+        "tide_corrected_only": str(tide_corrected_only).lower(),
+        "skip": str(skip),
+        "limit": str(limit),
+        "include_count": str(include_count).lower(),
+    }
+    if since_timestamp_utc is not None:
+        params["since_timestamp_utc"] = str(since_timestamp_utc)
+    return params
+
+
+async def get_history_data(
+    config: ClientConfig,
+    *,
+    latitude: float,
+    longitude: float,
+    radius_meters: float = 500,
+    since_timestamp_utc: float | None = None,
+    tide_corrected_only: bool = False,
+    skip: int = 0,
+    limit: int = 50000,
+    include_count: bool = True,
+) -> HistoryData:
+    """Request history data from the REST API.
+
+    Parameters
+    ----------
+    config
+        Client configuration.
+    latitude
+        Latitude in decimal degrees.
+    longitude
+        Longitude in decimal degrees.
+    radius_meters
+        Query radius in meters.
+    since_timestamp_utc
+        Return data collected or updated since this UTC epoch time.
+    tide_corrected_only
+        Only return tide corrected seafloor detections.
+    skip
+        Number of records to skip.
+    limit
+        Maximum number of records to return.
+    include_count
+        Include the total count in the response header.
+
+    Returns
+    -------
+    HistoryData
+        Parsed history data response.
+    """
+
+    port = resolve_rest_port(config, "GetHistoryData")
+    params = _build_history_params(
+        latitude=latitude,
+        longitude=longitude,
+        radius_meters=radius_meters,
+        since_timestamp_utc=since_timestamp_utc,
+        tide_corrected_only=tide_corrected_only,
+        skip=skip,
+        limit=limit,
+        include_count=include_count,
+    )
+    url = f"http://{config.host}:{port}/api/history_data"
+    try:
+        async with httpx.AsyncClient(timeout=config.timeout_seconds) as client:
+            response = await client.get(url, params=params)
+        response.raise_for_status()
+    except httpx.ConnectError as exc:
+        raise httpx.ConnectError(
+            f"Failed to connect to {url}, is the server running?"
+        ) from exc
+
+    history_count = None
+    if include_count:
+        header_val = response.headers.get("X-Grids-Count")
+        if header_val is not None:
+            try:
+                history_count = int(header_val)
+            except ValueError:
+                history_count = None
+    payload = response.json()
+    return HistoryData.from_dict(payload, history_count=history_count)