Skip to content

Beacon

beacon

X-Plane UDP Beacon Monitor

Beacon Monitor listen to X-Plane UDP multicast port for a «beacon» emitted by X-Plane network API, if enabled. If no beacon is ever detected, either X-Plane is not running, or it is busy starting. If a beacon is detected, the message contains connection information to reach X-Plane instance through the network. Beacon also contains information about the version of X-Plane.

Attributes:

  • logger (Logger) –

    Loger for functions and classes in this file.

Classes:

Functions:

  • list_my_ips –

    Utility function that list most if not all IP addresses of this host.

BEACON_DATA 


              flowchart TD
              xpwebapi.beacon.BEACON_DATA[BEACON_DATA]

              

              click xpwebapi.beacon.BEACON_DATA href "" "xpwebapi.beacon.BEACON_DATA"

X-Plane names of attributes inside its beacon.

BEACON_MONITOR_STATUS 


              flowchart TD
              xpwebapi.beacon.BEACON_MONITOR_STATUS[BEACON_MONITOR_STATUS]

              

              click xpwebapi.beacon.BEACON_MONITOR_STATUS href "" "xpwebapi.beacon.BEACON_MONITOR_STATUS"

Internal status of Beacon Monitor.

  • NOT_RUNNING - Beacon is not running
  • RUNNING - Beacon monitor is running but no beacon detected
  • DETECTING_BEACON - Beacon monitor is running and beacon detected

BeaconData dataclass 

BeaconData(host: str, port: int, hostname: str, xplane_version: int, role: int)

Pythonic dataclass to host X-Plane Beacon data.

XPBeaconMonitor 

XPBeaconMonitor(
    retry_attempts: int = 1, retry_backoff: float = 0.0, retry_backoff_max: float = 5.0
)

X-Plane «beacon» monitor.

Monitors X-Plane beacon which betrays X-Plane UDP port reachability. Beacon monitor listen for X-Plane beacon on UDP port. When beacon is detected, Beacon Monitor calls back a user-supplied function whenever the reachability status changes.

Attributes:

  • MCAST_GRP (str) –

    default 239.255.1.1

  • MCAST_PORT (int) –

    default 49707 (MCAST_PORT was 49000 for XPlane10)

  • BEACON_TIMEOUT (float) –

    default 3.0 seconds

  • MAX_WARNING (int) –

    After MAX_WARNING warnings of "no connection", stops reporting "no connection". Default 3.

  • BEACON_PROBING_TIMEOUT (float) –

    Times between attempts to reconnect to X-Plane when not connected (default 10 seconds)

  • WARN_FREQ (float) –

    Report absence of connection every WARN_FREQ seconds. Default 10 seconds.

  • socket (socket | None) –

    Socket to multicast listener

  • status (BEACON_MONITOR_STATUS) –

    Beacon monitor status

  • data (BeaconData | None) –

    BeaconData | None - Beacon data as broadcasted by X-Plane in its beacon. None if beacon is not received.

  • my_ips (list[str]) –

    List of this host IP addresses

  • _already_warned (bool) –
  • _callback (set[Callable]) –

    (Callable | None):

  • should_not_connect (Event) –
  • connect_thread (Event) –

    (threading.Thread | None):

Usage;

import xpwebapi


def callback(connected: bool, beacon_data: xpwebapi.BeaconData, same_host: bool):
    print("reachable" if connected else "unreachable")


beacon = xpwebapi.beacon()
beacon.set_callback(callback)
beacon.start_monitor()

Methods:

  • callback –

    Execute all callback functions

  • get_beacon –

    Attempts to capture an X-Plane beacon using configured transient retries.

  • same_host –

    Attempt to determine if X-Plane is running on local host (where beacon monitor runs) or remote host

  • set_callback –

    Add callback function

  • start_monitor –

    Starts beacon monitor

  • stop_monitor –

    Terminates beacon monitor

consecutive_failures property 

consecutive_failures: int

Returns number of recent consecutive failures

This can be used to detect temporary failures. When X-Plane is extremely busy, it may not send a beacon, or beacon emission can be delayed. X-Plane is up and running but no beacon has been detected. "Missing" a few detections in a row does not mean X-Plane is not running. This consecutive_failures allows to wait for a few failures to detect X-Plane before concluding its unavailability.

receiving_beacon property 

receiving_beacon: bool

Returns whether beacon from X-Plane is periodically received

status property writable 

status: BEACON_MONITOR_STATUS

Report beacon monitor status

returns:

BEACON_MONITOR_STATUS: Monitor status

status_str property 

status_str: str

Report beacon monitor status as a string

callback 

callback(connected: bool, beacon_data: BeaconData | None, same_host: bool | None)

Execute all callback functions

Callback function prototype

callback(connected: bool, beacon_data: BeaconData | None, same_host: bool | None)

Connected is True is beacon is detected at regular interval, False otherwise

get_beacon 

get_beacon(timeout: float = BEACON_TIMEOUT) -> BeaconData | None

Attempts to capture an X-Plane beacon using configured transient retries.

same_host 

same_host() -> bool

Attempt to determine if X-Plane is running on local host (where beacon monitor runs) or remote host

set_callback 

set_callback(callback: Callable | None = None)

Add callback function

Callback functions will be called whenever the status of the "connection" changes.

Parameters:

  • callback

    (Callable, default: None ) –

    Callback function Callback function prototype

    callback(connected: bool, beacon_data: BeaconData | None, same_host: bool | None)

Connected is True is beacon is detected at regular interval, False otherwise

start_monitor 

start_monitor()

Starts beacon monitor

stop_monitor 

stop_monitor()

Terminates beacon monitor

list_my_ips 

list_my_ips() -> list[str]

Utility function that list most if not all IP addresses of this host.

Returns:

  • list[str] –

    list[str]: List of IP v4 addresses of this host on most, if not all interfaces (cable, wi-fi, bluetooth...)