fsd9lib 0.1.0__py3-none-any.whl

fsd9/__init__.py

@@ -0,0 +1,102 @@
+"""
+FSD9 — A Python library for FSD (Flight Simulator Data) protocol v9.
+
+Provides a complete implementation of the classic FSD protocol for
+VATSIM-compatible pilot client connections. Supports protocol revision 9
+(legacy plaintext authentication).
+
+Quick start::
+
+    import asyncio
+    from fsd9 import PilotClient
+
+    async def main():
+        client = PilotClient(
+            callsign="N7938C",
+            cid="123456",
+            password="secret",
+            server="eu.velocity.vatsim.net",
+        )
+
+        async def on_msg(client, sender, text):
+            print(f"[{sender}] {text}")
+
+        client.on_message = on_msg
+
+        await client.connect()
+        await client.send_position(40.659, -73.798, 35000, 450, 2.0, 0.0, 90.0)
+        # ... do stuff ...
+        await client.disconnect()
+
+    asyncio.run(main())
+"""
+
+from .client import PilotClient
+from .connection import FSDConnection
+from .constants import (
+    Capability,
+    FacilityType,
+    FlightRules,
+    NetworkRating,
+    PilotRating,
+    Recipient,
+    ServerError,
+    SimulatorType,
+    TransponderMode,
+    FSD_DEFAULT_PORT,
+    PROTOCOL_REVISION_CLASSIC,
+    CALLSIGN_MIN_LENGTH,
+    CALLSIGN_MAX_LENGTH,
+    KNOWN_CLIENT_IDS,
+    ATC_VISUAL_RANGES,
+)
+from .errors import (
+    FSDError,
+    FSDConnectionError,
+    FSDLoginError,
+    FSDProtocolError,
+    FSDServerError,
+    FSDCallsignError,
+    FSDSquawkError,
+    FSDFrequencyError,
+)
+from . import frequency
+from . import pbh
+from . import packet
+
+__version__ = "0.1.0"
+__all__ = [
+    # Client
+    "PilotClient",
+    "FSDConnection",
+    # Enums
+    "NetworkRating",
+    "PilotRating",
+    "SimulatorType",
+    "FacilityType",
+    "TransponderMode",
+    "FlightRules",
+    "ServerError",
+    "Capability",
+    "Recipient",
+    # Constants
+    "FSD_DEFAULT_PORT",
+    "PROTOCOL_REVISION_CLASSIC",
+    "CALLSIGN_MIN_LENGTH",
+    "CALLSIGN_MAX_LENGTH",
+    "KNOWN_CLIENT_IDS",
+    "ATC_VISUAL_RANGES",
+    # Errors
+    "FSDError",
+    "FSDConnectionError",
+    "FSDLoginError",
+    "FSDProtocolError",
+    "FSDServerError",
+    "FSDCallsignError",
+    "FSDSquawkError",
+    "FSDFrequencyError",
+    # Modules
+    "frequency",
+    "pbh",
+    "packet",
+]

fsd9/client.py

@@ -0,0 +1,558 @@
+"""
+High-level FSD Protocol v9 Pilot Client.
+
+Provides a simple async API for connecting to an FSD server as a pilot
+(flight crew), sending position updates, filing flight plans, and
+receiving messages.
+
+Usage::
+
+    import asyncio
+    from fsd9 import PilotClient, NetworkRating, SimulatorType
+
+    async def main():
+        client = PilotClient(
+            callsign="N7938C",
+            cid="123456",
+            password="secret",
+            server="eu.velocity.vatsim.net",
+        )
+        client.on_message = lambda msg: print(f"[MSG] {msg}")
+
+        await client.connect()
+
+        # Send position every 5 seconds
+        await client.send_position(40.65906, -73.79891, 35000, 450, 2.0, 0.0, 90.0)
+
+        await client.disconnect()
+
+    asyncio.run(main())
+"""
+
+import asyncio
+import logging
+import math
+import time
+from typing import Optional, Callable, Awaitable
+
+from .connection import FSDConnection
+from .constants import (
+    FSD_DEFAULT_PORT,
+    NetworkRating,
+    PilotRating,
+    SimulatorType,
+    TransponderMode,
+    FlightRules,
+    Recipient,
+    ServerError,
+)
+from .errors import FSDError, FSDLoginError, FSDServerError
+from . import packet
+from . import frequency as _freq
+
+logger = logging.getLogger(__name__)
+
+# Callback type aliases
+MessageCallback = Callable[["PilotClient", str, str], Awaitable[None]]
+"""Callback for text messages: (client, sender, message)"""
+
+PositionCallback = Callable[["PilotClient", str, dict], Awaitable[None]]
+"""Callback for position updates: (client, callsign, parsed_position)"""
+
+ErrorCallback = Callable[["PilotClient", FSDServerError], Awaitable[None]]
+"""Callback for server errors: (client, error)"""
+
+
+class PilotClient:
+    """Async FSD protocol v9 pilot client.
+
+    Handles login, position updates, flight plan filing, text messaging,
+    and all incoming message parsing.
+
+    Attributes:
+        callsign: The pilot's callsign
+        cid: VATSIM Certificate ID
+        connected: Whether currently connected and logged in
+    """
+
+    def __init__(
+        self,
+        callsign: str,
+        cid: str,
+        password: str,
+        server: str = "eu.velocity.vatsim.net",
+        port: int = FSD_DEFAULT_PORT,
+        *,
+        real_name: str = "",
+        sim_type: SimulatorType = SimulatorType.MSFS2020,
+        network_rating: NetworkRating = NetworkRating.OBS,
+        protocol_revision: int = 9,
+        client_name: str = "fsd9lib",
+        # Position state
+        auto_position: bool = False,
+        position_interval: float = 5.0,
+    ):
+        """Initialize the pilot client.
+
+        Args:
+            callsign: Pilot callsign (3–11 characters)
+            cid: VATSIM Certificate ID
+            password: Plaintext password (protocol 9)
+            server: FSD server hostname
+            port: FSD server port (default 6809)
+            real_name: Pilot's real name
+            sim_type: Simulator type enum
+            network_rating: Pilot network rating
+            protocol_revision: Protocol revision (9 for classic)
+            client_name: Human-readable client name for logging
+            auto_position: If True, automatically send position at interval
+            position_interval: Position update interval in seconds (default 5s)
+        """
+        self.callsign = callsign
+        self.cid = cid
+        self.password = password
+        self.real_name = real_name
+        self.sim_type = sim_type
+        self.network_rating = network_rating
+        self.protocol_revision = protocol_revision
+        self.client_name = client_name
+
+        self._conn = FSDConnection(server, port, reconnect=False)
+        self._server = server
+        self._port = port
+
+        # Connection state
+        self._connected = False
+        self._logged_in = False
+        self._running = False
+        self._read_task: Optional[asyncio.Task] = None
+        self._position_task: Optional[asyncio.Task] = None
+
+        # Position auto-send
+        self.auto_position = auto_position
+        self.position_interval = position_interval
+
+        # Current position state (for auto-send)
+        self._current_position: Optional[dict] = None
+
+        # Callbacks
+        self.on_message: Optional[MessageCallback] = None
+        self.on_position: Optional[PositionCallback] = None
+        self.on_atc_position: Optional[PositionCallback] = None
+        self.on_error: Optional[ErrorCallback] = None
+        self.on_disconnect: Optional[Callable[["PilotClient"], Awaitable[None]]] = None
+
+        # Known clients (callsign → last parsed position)
+        self.known_clients: dict[str, dict] = {}
+        self.known_atc: dict[str, dict] = {}
+
+    # ── properties ───────────────────────────────────────────────────────
+
+    @property
+    def connected(self) -> bool:
+        return self._connected and self._logged_in
+
+    @property
+    def server(self) -> str:
+        return f"{self._server}:{self._port}"
+
+    # ── connection lifecycle ─────────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Connect to the FSD server and log in as a pilot.
+
+        Protocol 9 flow:
+            1. Open TCP connection
+            2. Send #AP with plaintext password
+            3. Server validates and broadcasts login
+
+        Raises:
+            FSDLoginError: If login fails
+            FSDError: On protocol errors
+        """
+        await self._conn.connect()
+
+        # Send login (protocol 9: simple plaintext login)
+        login_pkt = packet.build_add_pilot(
+            callsign=self.callsign,
+            cid=self.cid,
+            password=self.password,
+            network_rating=self.network_rating,
+            protocol_revision=self.protocol_revision,
+            sim_type=self.sim_type,
+            real_name=self.real_name,
+        )
+        await self._conn.send_line(login_pkt)
+        logger.info(f"Sent login for {self.callsign}")
+
+        self._connected = True
+        self._logged_in = True
+        self._running = True
+
+        # Start message reader
+        self._read_task = asyncio.create_task(self._read_loop())
+
+        # Start auto-position if enabled
+        if self.auto_position:
+            self._position_task = asyncio.create_task(self._auto_position_loop())
+
+        logger.info(f"Logged in as {self.callsign} on {self.server}")
+
+    async def disconnect(self) -> None:
+        """Disconnect from the server gracefully."""
+        self._running = False
+
+        # Send logout
+        if self._logged_in:
+            try:
+                logout = packet.build_delete_pilot(self.callsign, self.cid)
+                await self._conn.send_line(logout)
+            except Exception:
+                pass
+
+        # Cancel tasks
+        for task in (self._read_task, self._position_task):
+            if task and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+
+        self._read_task = None
+        self._position_task = None
+
+        await self._conn.disconnect()
+        self._connected = False
+        self._logged_in = False
+
+        if self.on_disconnect:
+            try:
+                await self.on_disconnect(self)
+            except Exception as e:
+                logger.warning(f"on_disconnect callback failed: {e}")
+
+    # ── message reading ──────────────────────────────────────────────────
+
+    async def _read_loop(self) -> None:
+        """Main loop: read and dispatch incoming messages."""
+        while self._running:
+            try:
+                line = await self._conn.read_line()
+            except Exception as e:
+                logger.error(f"Read error: {e}")
+                break
+
+            if line is None:
+                break
+
+            try:
+                await self._dispatch(line)
+            except Exception as e:
+                logger.debug(f"Dispatch error for line {line!r}: {e}")
+
+        # Connection lost
+        self._connected = False
+        self._logged_in = False
+        if self.on_disconnect:
+            try:
+                await self.on_disconnect(self)
+            except Exception:
+                pass
+
+    async def _dispatch(self, line: str) -> None:
+        """Parse and dispatch a single incoming line."""
+        fields = line.rstrip("\r\n").split(":")
+
+        if not fields or not fields[0]:
+            return
+
+        prefix = packet.get_pdu_prefix(line)
+
+        # ── Pilot position ──
+        if prefix == "@":
+            data = packet.parse_pilot_position(fields)
+            cs = data["callsign"]
+            self.known_clients[cs] = data
+            if self.on_position and cs != self.callsign:
+                await self.on_position(self, cs, data)
+
+        # ── ATC position ──
+        elif prefix == "%":
+            data = packet.parse_atc_position(fields)
+            cs = data["callsign"]
+            self.known_atc[cs] = data
+            if self.on_atc_position:
+                await self.on_atc_position(self, cs, data)
+
+        # ── Fast positions ──
+        elif prefix in ("^", "#SL", "#ST"):
+            data = packet.parse_fast_position(fields)
+            cs = data["callsign"]
+            self.known_clients[cs] = data
+            if self.on_position and cs != self.callsign:
+                await self.on_position(self, cs, data)
+
+        # ── Text message ──
+        elif prefix == "#TM":
+            data = packet.parse_text_message(fields)
+            sender = data["sender"]
+            if sender != self.callsign and self.on_message:
+                await self.on_message(self, sender, data["message"])
+
+        # ── Server error ──
+        elif prefix == "$ER":
+            data = packet.parse_server_error(fields)
+            code = ServerError(data["error_code"])
+            err = FSDServerError(code, data["param"], data["description"])
+            if err.is_fatal:
+                logger.error(f"Fatal server error: {err}")
+                self._running = False
+            if self.on_error:
+                await self.on_error(self, err)
+
+        # ── Kill ──
+        elif prefix == "$!!":
+            data = packet.parse_kill(fields)
+            logger.warning(f"Killed by {data['sender']}: {data['reason']}")
+            self._running = False
+
+        # ── Ping ──
+        elif prefix == "$PI":
+            data = packet.parse_client_query(fields)
+            # Respond with pong
+            await self.send_pong(data["receiver"])
+
+        # ── #SB plane info request ──
+        elif prefix == "#SB":
+            # Silently acknowledge but we don't auto-respond
+            pass
+
+        # ── Client added/removed ──
+        elif prefix in ("#AP", "#DP", "#DA"):
+            # Track logins/logouts (simplified)
+            pass
+
+    # ── sending methods ──────────────────────────────────────────────────
+
+    async def _send(self, raw: str) -> None:
+        """Send a raw packet line. Raises if not connected."""
+        if not self.connected:
+            raise FSDError("Not connected and logged in")
+        await self._conn.send_line(raw)
+
+    async def send_position(
+        self,
+        lat: float,
+        lon: float,
+        altitude_true: int,
+        ground_speed: int,
+        pitch: float = 0.0,
+        bank: float = 0.0,
+        heading: float = 0.0,
+        *,
+        squawk: int = 0o2000,
+        transponder_mode: str = "N",
+        altitude_correction: int = 0,
+        on_ground: bool = False,
+    ) -> None:
+        """Send a pilot position update (@ packet).
+
+        Args:
+            lat: Latitude in decimal degrees
+            lon: Longitude in decimal degrees
+            altitude_true: True altitude in feet
+            ground_speed: Ground speed in knots
+            pitch: Pitch angle in degrees
+            bank: Bank angle in degrees
+            heading: Heading in degrees
+            squawk: 4-digit octal squawk code
+            transponder_mode: 'S' (standby), 'N' (mode C), 'Y' (ident)
+            altitude_correction: PressureAlt - TrueAlt in feet
+            on_ground: Whether on the ground
+        """
+        pkt = packet.build_pilot_position(
+            callsign=self.callsign,
+            transponder_mode=transponder_mode,
+            squawk=squawk,
+            network_rating=self.network_rating,
+            lat=lat,
+            lon=lon,
+            altitude_true=altitude_true,
+            ground_speed=ground_speed,
+            pitch=pitch,
+            bank=bank,
+            heading=heading,
+            altitude_correction=altitude_correction,
+            on_ground=on_ground,
+        )
+        await self._send(pkt)
+
+        # Store for auto-send
+        self._current_position = {
+            "lat": lat,
+            "lon": lon,
+            "altitude_true": altitude_true,
+            "ground_speed": ground_speed,
+            "pitch": pitch,
+            "bank": bank,
+            "heading": heading,
+            "squawk": squawk,
+            "transponder_mode": transponder_mode,
+            "altitude_correction": altitude_correction,
+            "on_ground": on_ground,
+        }
+
+    async def _auto_position_loop(self) -> None:
+        """Auto-send position updates at regular intervals."""
+        while self._running:
+            await asyncio.sleep(self.position_interval)
+            if self._current_position and self.connected:
+                try:
+                    await self.send_position(**self._current_position)
+                except Exception as e:
+                    logger.warning(f"Auto-position send failed: {e}")
+
+    async def send_text(self, receiver: str, message: str) -> None:
+        """Send a text message.
+
+        Receiver can be:
+            - A specific callsign (e.g. "EGLL_TWR")
+            - @{freq} for radio (e.g. "@22800")
+            - * for all, *A for all ATC, *P for all pilots
+            - @49999 for ATC chat room
+        """
+        pkt = packet.build_text_message(self.callsign, receiver, message)
+        await self._send(pkt)
+
+    async def send_radio_message(self, frequency_mhz: float, message: str) -> None:
+        """Send a message on a radio frequency.
+
+        Args:
+            frequency_mhz: Frequency in MHz (e.g. 122.800)
+            message: Message text
+        """
+        wire = _freq.encode(frequency_mhz)
+        receiver = f"@{wire}"
+        await self.send_text(receiver, message)
+
+    async def file_flight_plan(
+        self,
+        flight_rules: str = FlightRules.IFR,
+        equipment: str = "",
+        tas: int = 0,
+        dep_airport: str = "",
+        est_dep_time: str = "",
+        act_dep_time: str = "",
+        cruise_alt: int = 0,
+        dest_airport: str = "",
+        hrs_enroute: int = 0,
+        min_enroute: int = 0,
+        hrs_fuel: int = 0,
+        min_fuel: int = 0,
+        alt_airport: str = "",
+        remarks: str = "",
+        route: str = "",
+    ) -> None:
+        """File a flight plan to the server.
+
+        Args:
+            flight_rules: 'I'=IFR, 'V'=VFR, 'S'=SVFR, 'D'=DVFR
+            equipment: FAA/ICAO equipment suffix (e.g. "H/B772/L")
+            tas: True airspeed in knots
+            dep_airport: Departure airport ICAO
+            est_dep_time: Estimated departure time (HHMM)
+            act_dep_time: Actual departure time (HHMM)
+            cruise_alt: Cruise altitude in feet
+            dest_airport: Destination airport ICAO
+            hrs_enroute: Hours enroute
+            min_enroute: Minutes enroute (additional)
+            hrs_fuel: Hours of fuel
+            min_fuel: Minutes of fuel (additional)
+            alt_airport: Alternate airport ICAO
+            remarks: Remarks
+            route: Route string (SIDs, airways, STARs, etc.)
+        """
+        pkt = packet.build_flight_plan(
+            callsign=self.callsign,
+            flight_rules=flight_rules,
+            equipment=equipment,
+            tas=tas,
+            dep_airport=dep_airport,
+            est_dep_time=est_dep_time,
+            act_dep_time=act_dep_time,
+            cruise_alt=cruise_alt,
+            dest_airport=dest_airport,
+            hrs_enroute=hrs_enroute,
+            min_enroute=min_enroute,
+            hrs_fuel=hrs_fuel,
+            min_fuel=min_fuel,
+            alt_airport=alt_airport,
+            remarks=remarks,
+            route=route,
+        )
+        await self._send(pkt)
+        logger.info(f"Filed flight plan {dep_airport}→{dest_airport} at FL{cruise_alt // 100}")
+
+    async def send_plane_info(
+        self,
+        target: str,
+        equipment: str = "",
+        airline: str = "",
+        livery: str = "",
+    ) -> None:
+        """Send plane information to another client (model matching).
+
+        Args:
+            target: Target callsign
+            equipment: Aircraft ICAO (e.g. "B738")
+            airline: Airline ICAO (e.g. "DAL")
+            livery: Livery identifier
+        """
+        pkt = packet.build_sb_plane_info(
+            sender=self.callsign,
+            target=target,
+            equipment=equipment,
+            airline=airline,
+            livery=livery,
+        )
+        await self._send(pkt)
+
+    async def request_metar(self, icao: str) -> None:
+        """Request a METAR from the server.
+
+        The METAR will arrive as a $AR packet; handle it via the
+        message reader loop (currently logged but not specially dispatched).
+        """
+        pkt = packet.build_metar_request(self.callsign, icao)
+        await self._send(pkt)
+
+    async def send_ping(self, receiver: str = Recipient.SERVER) -> None:
+        """Send a ping (keepalive)."""
+        pkt = packet.build_ping(self.callsign, receiver)
+        await self._send(pkt)
+
+    async def send_pong(self, receiver: str = Recipient.SERVER) -> None:
+        """Send a pong (ping response)."""
+        pkt = packet.build_pong(self.callsign, receiver)
+        await self._send(pkt)
+
+    async def request_atis(self, atc_callsign: str) -> None:
+        """Request ATIS information from an ATC client.
+
+        The response comes as multiple $CR...ATIS packets handled in the
+        read loop.
+        """
+        pkt = packet.build_client_query(
+            self.callsign, atc_callsign, "ATIS"
+        )
+        await self._send(pkt)
+
+    # ── utility ──────────────────────────────────────────────────────────
+
+    def pilot_visual_range(self, altitude_ft: int) -> float:
+        """Calculate pilot visual range in nautical miles.
+
+        Range = 10 + 1.414 * sqrt(altitude_ft)
+        """
+        return 10.0 + 1.414 * math.sqrt(max(altitude_ft, 0))