Core API

api

Abstract base classes and core classes like Dataref and Command.

Classes:

API –

Protocol with shared API connection helpers.
APIObjMeta –

Container for XP Web API models meta data
CONNECTION_STATUS –

Internal Beacon Connector status
Cache –

Backward-compatible generic metadata cache.
Command –

X-Plane Web API Command
CommandCache –

Stores command metadata in cache.
CommandMeta –

Container for XP Web API command meta data
DATAREF_DATATYPE –

X-Plane API dataref types
Dataref –

X-Plane Web API Dataref
DatarefCache –

Stores dataref metadata in cache.
DatarefMeta –

Container for XP Web API dataref meta data
MetaCacheBase –

Stores X-Plane Web API metadata in cache.
ValueCache –

Utility class to round a dataref value and determine if it has changed.
XPLANE_API_VERSIONS –

API version number (string) versus X-Plane release number when that API version appeared for the first time

API

API(host: str, port: int, api: str, api_version: str, read_only: bool = False)


              flowchart TD
              xpwebapi.api.API[API]

              

              click xpwebapi.api.API href "" "xpwebapi.api.API"

Protocol with shared API connection helpers.

Methods:

beacon_callback –

Minimal beacon callback function.
changed –

If rounding applies, determine if value has changed according to its rounding.
command –

Create Command with current API
dataref –

Create Dataref with current API
dataref_value –

Returns Dataref value from simulator
execute_command –

Execute command
set_network –

Set network and API parameters for connection
set_roundings –

Add rounding to simulator variable value.
write_dataref –

Write Dataref value to X-Plane if Dataref is writable

Attributes:

connected (bool) –

Whether X-Plane API is reachable through this instance
rest_url (str) –

URL for the REST API
status (CONNECTION_STATUS) –

Connection status
status_str (str) –

Connection status as a string
use_rest (bool) –

Should use REST API for some purpose

connected `property`

connected: bool

Whether X-Plane API is reachable through this instance

rest_url `property`

rest_url: str

URL for the REST API

status `property` `writable`

status: CONNECTION_STATUS

Connection status

status_str `property`

status_str: str

Connection status as a string

use_rest `property` `writable`

use_rest: bool

Should use REST API for some purpose

beacon_callback

beacon_callback(connected: bool, beacon_data: 'BeaconData', same_host: bool)

Minimal beacon callback function.

Provided for convenience.

Parameters:

connected
(bool) –

Whether beacon is received
beacon_data
(BeaconData) –

Beacon data
same_host
(bool) –

Whether beacon is issued from same host as host running the monitor

changed

changed(dataref, value) -> bool

If rounding applies, determine if value has changed according to its rounding.

command

command(path: str) -> Command

Create Command with current API

Parameters:

path
(str) –

Command "path"

Returns:

Command ( Command ) –

Created command

dataref

dataref(path: str, auto_save: bool = False) -> Dataref

Create Dataref with current API

Parameters:

path
(str) –

Dataref "path"
auto_save
(bool, default: False ) –

Save dataref back to X-Plane if value has changed and writable (default: False)

Returns:

Dataref ( Dataref ) –

Created dataref

dataref_value

dataref_value(
    dataref: Dataref, raw: bool = False, no_decode: bool = False
) -> DatarefReadResult

Returns Dataref value from simulator

Parameters:

dataref
(Dataref) –

Dataref to get the value from
raw
(bool, default: False ) –

Return raw value without decoding (default: False)
no_decode
(bool, default: False ) –

Skip base64 decoding for data types (default: False)

Returns:

DatarefReadResult ( DatarefReadResult ) –

Value of dataref.

execute_command

execute_command(command: Command, duration: float = 0.0) -> APIResult

Execute command

Parameters:

command
(Command) –

Command to execute
duration
(float, default: 0.0 ) –

Duration of execution for long commands (default: 0.0)

Returns:

APIResult ( APIResult ) –

True/False for immediate APIs, or a request id for queued APIs.

set_network

set_network(host: str, port: int, api: str, api_version: str) -> bool

Set network and API parameters for connection

Parameters:

host
(str) –

Host name or IP address
port
(int) –

TCP port number for API
api
(str) –

API root path, starts with /.
api_version
(str) –

API version string, starts with /, appended to api string to form full path to API.

Returns:

bool ( bool ) –

True if some network parameter has changed

set_roundings

set_roundings(roundings)

Add rounding to simulator variable value. Rounding is applied to value before it is sent to callback function.

write_dataref

write_dataref(dataref: Dataref) -> APIResult

Write Dataref value to X-Plane if Dataref is writable

Parameters:

dataref
(Dataref) –

Dataref to write

Returns:

APIResult ( APIResult ) –

True/False for immediate APIs, or a request id for queued APIs.

APIObjMeta

APIObjMeta(name: str, ident: int)


              flowchart TD
              xpwebapi.api.APIObjMeta[APIObjMeta]

              

              click xpwebapi.api.APIObjMeta href "" "xpwebapi.api.APIObjMeta"

Container for XP Web API models meta data

CONNECTION_STATUS


              flowchart TD
              xpwebapi.api.CONNECTION_STATUS[CONNECTION_STATUS]

              

              click xpwebapi.api.CONNECTION_STATUS href "" "xpwebapi.api.CONNECTION_STATUS"

Internal Beacon Connector status

Cache

Cache(api)


              flowchart TD
              xpwebapi.api.Cache[Cache]
              xpwebapi.api.MetaCacheBase[MetaCacheBase]

                              xpwebapi.api.MetaCacheBase --> xpwebapi.api.Cache
                


              click xpwebapi.api.Cache href "" "xpwebapi.api.Cache"
              click xpwebapi.api.MetaCacheBase href "" "xpwebapi.api.MetaCacheBase"

Backward-compatible generic metadata cache.

Prefer DatarefCache or CommandCache for new code.

Methods:

equiv –

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)
get –

Get meta data from cache by name
get_by_id –

Get meta data from cache by dataref or command identifier
get_by_name –

Get meta data from cache by name
load –

Load cache data, preserving the old optional path argument.
meta –

Create metadata using the legacy dataref/command heuristic.
save –

Saved cached data into file

Attributes:

count (int) –

Number of data in cache
has_data (bool) –

Cache contains data

count `property`

count: int

Number of data in cache

has_data `property`

has_data: bool

Cache contains data

equiv

equiv(ident) -> str | None

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)

get

get(name) -> APIObjMeta | None

Get meta data from cache by name

get_by_id

get_by_id(ident: int) -> APIObjMeta | None

Get meta data from cache by dataref or command identifier

get_by_name

get_by_name(name) -> APIObjMeta | None

Get meta data from cache by name

load

load(path: str | None = None)

Load cache data, preserving the old optional path argument.

meta `classmethod`

meta(**kwargs) -> DatarefMeta | CommandMeta

Create metadata using the legacy dataref/command heuristic.

save

save(filename)

Saved cached data into file

Command

Command(api: API, path: str, duration: float = 0.0)

X-Plane Web API Command

Methods:

execute –

Execute command through API supplied at creation
monitor –

Monitor command activation through Websocket API
unmonitor –

Suppress monitor command activation through Websocket API

Attributes:

description (str | None) –

Get command description as provided by X-Plane
ident (int | None) –

Get command identifier meta data
meta (CommandMeta | None) –

Meta data of command
valid (bool) –

Returns whether meta data for command was acquired sucessfully to carry on operations on it

description `property`

description: str | None

Get command description as provided by X-Plane

ident `property`

ident: int | None

Get command identifier meta data

meta `property`

meta: CommandMeta | None

Meta data of command

valid `property`

valid: bool

Returns whether meta data for command was acquired sucessfully to carry on operations on it

execute

execute(duration: float = 0.0) -> APIResult

Execute command through API supplied at creation

monitor

monitor(on: bool = True) -> bool

Monitor command activation through Websocket API

unmonitor

unmonitor() -> bool

Suppress monitor command activation through Websocket API

CommandCache

CommandCache(api)


              flowchart TD
              xpwebapi.api.CommandCache[CommandCache]
              xpwebapi.api.MetaCacheBase[MetaCacheBase]

                              xpwebapi.api.MetaCacheBase --> xpwebapi.api.CommandCache
                


              click xpwebapi.api.CommandCache href "" "xpwebapi.api.CommandCache"
              click xpwebapi.api.MetaCacheBase href "" "xpwebapi.api.MetaCacheBase"

Stores command metadata in cache.

Methods:

equiv –

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)
get –

Get command metadata from cache by name.
get_by_id –

Get command metadata from cache by identifier.
get_by_name –

Get command metadata from cache by name.
load –

Load cache data
meta –

Create CommandMeta from dictionary returned by X-Plane Web API.
save –

Saved cached data into file

Attributes:

count (int) –

Number of data in cache
has_data (bool) –

Cache contains data

count `property`

count: int

Number of data in cache

has_data `property`

has_data: bool

Cache contains data

equiv

equiv(ident) -> str | None

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)

get

get(name) -> CommandMeta | None

Get command metadata from cache by name.

get_by_id

get_by_id(ident: int) -> CommandMeta | None

Get command metadata from cache by identifier.

get_by_name

get_by_name(name) -> CommandMeta | None

Get command metadata from cache by name.

load

load()

Load cache data

meta `classmethod`

meta(**kwargs) -> CommandMeta

Create CommandMeta from dictionary returned by X-Plane Web API.

save

save(filename)

Saved cached data into file

CommandMeta

CommandMeta(name: str, description: str, **kwargs)


              flowchart TD
              xpwebapi.api.CommandMeta[CommandMeta]
              xpwebapi.api.APIObjMeta[APIObjMeta]

                              xpwebapi.api.APIObjMeta --> xpwebapi.api.CommandMeta
                


              click xpwebapi.api.CommandMeta href "" "xpwebapi.api.CommandMeta"
              click xpwebapi.api.APIObjMeta href "" "xpwebapi.api.APIObjMeta"

Container for XP Web API command meta data

DATAREF_DATATYPE


              flowchart TD
              xpwebapi.api.DATAREF_DATATYPE[DATAREF_DATATYPE]

              

              click xpwebapi.api.DATAREF_DATATYPE href "" "xpwebapi.api.DATAREF_DATATYPE"

X-Plane API dataref types

Dataref

Dataref(path: str, api: API, auto_save: bool = False)

X-Plane Web API Dataref

Methods:

dec_monitor –

Unregister dataref from monitoring
get_string_value –

Decodes current dataref value and replaces it with the decoded string value
get_value –

Return current value of dataref in local application
inc_monitor –

Register dataref for monitoring
monitor –

Monitor dataref value change
set_string_value –

Set dataref value to base64 encoded representation of string value
unmonitor –

Unmonitor dataref value change
write –

Write new value to X-Plane through REST API

Attributes:

ident (int | None) –

Get dataref identifier meta data
is_array (bool) –

Whether dataref is an array
is_monitored –

Whether dataref is currently monitored
is_writable (bool) –

Whether dataref can be written back to X-Plane
last_updated (datetime) –

Returns last time of modification
meta (DatarefMeta | None) –

Meta data of dataref
monitored_count (int) –

How many times dataref is monitored
valid (bool) –

Returns whether meta data for dataref was acquired sucessfully to carry on operations on it
value –

Return current value of dataref in local application
value_type (str | None) –

Get dataref value type meta data

ident `property`

ident: int | None

Get dataref identifier meta data

is_array `property`

is_array: bool

Whether dataref is an array

is_monitored `property`

is_monitored

Whether dataref is currently monitored

is_writable `property`

is_writable: bool

Whether dataref can be written back to X-Plane

last_updated `property`

last_updated: datetime

Returns last time of modification

meta `property`

meta: DatarefMeta | None

Meta data of dataref

monitored_count `property`

monitored_count: int

How many times dataref is monitored

valid `property`

valid: bool

Returns whether meta data for dataref was acquired sucessfully to carry on operations on it

value `property` `writable`

value

Return current value of dataref in local application

value_type `property`

value_type: str | None

Get dataref value type meta data

Valid value types are

INTEGER = "int"
FLOAT = "float"
DOUBLE = "double"
INTARRAY = "int_array"
FLOATARRAY = "float_array"
DATA = "data"

dec_monitor

dec_monitor() -> bool

Unregister dataref from monitoring

Returns bool: Whether dataref is still monitored after this unmonitoring() call

get_string_value

get_string_value(encoding: str) -> str | None

Decodes current dataref value and replaces it with the decoded string value

Parameters:

encoding
(str) –

Encoding used to decode the bytes value.

Returns:

str | None –

get_value

get_value()

Return current value of dataref in local application

inc_monitor

inc_monitor()

Register dataref for monitoring

monitor

monitor() -> bool

Monitor dataref value change

set_string_value

set_string_value(value: str, encoding: str)

Set dataref value to base64 encoded representation of string value

[description]

Parameters:

value
(str) –

[description]
encoding
(str) –

[description]

unmonitor

unmonitor() -> bool

Unmonitor dataref value change

write

write() -> APIResult

Write new value to X-Plane through REST API

Dataref value is saved locally and written to X-Plane when write() or save() is called.

DatarefCache

DatarefCache(api)


              flowchart TD
              xpwebapi.api.DatarefCache[DatarefCache]
              xpwebapi.api.MetaCacheBase[MetaCacheBase]

                              xpwebapi.api.MetaCacheBase --> xpwebapi.api.DatarefCache
                


              click xpwebapi.api.DatarefCache href "" "xpwebapi.api.DatarefCache"
              click xpwebapi.api.MetaCacheBase href "" "xpwebapi.api.MetaCacheBase"

Stores dataref metadata in cache.

Methods:

equiv –

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)
get –

Get dataref metadata from cache by name.
get_by_id –

Get dataref metadata from cache by identifier.
get_by_name –

Get dataref metadata from cache by name.
load –

Load cache data
meta –

Create DatarefMeta from dictionary returned by X-Plane Web API.
save –

Saved cached data into file

Attributes:

count (int) –

Number of data in cache
has_data (bool) –

Cache contains data

count `property`

count: int

Number of data in cache

has_data `property`

has_data: bool

Cache contains data

equiv

equiv(ident) -> str | None

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)

get

get(name) -> DatarefMeta | None

Get dataref metadata from cache by name.

get_by_id

get_by_id(ident: int) -> DatarefMeta | None

Get dataref metadata from cache by identifier.

get_by_name

get_by_name(name) -> DatarefMeta | None

Get dataref metadata from cache by name.

load

load()

Load cache data

meta `classmethod`

meta(**kwargs) -> DatarefMeta

Create DatarefMeta from dictionary returned by X-Plane Web API.

save

save(filename)

Saved cached data into file

DatarefMeta

DatarefMeta(name: str, value_type: str, is_writable: bool, **kwargs)


              flowchart TD
              xpwebapi.api.DatarefMeta[DatarefMeta]
              xpwebapi.api.APIObjMeta[APIObjMeta]

                              xpwebapi.api.APIObjMeta --> xpwebapi.api.DatarefMeta
                


              click xpwebapi.api.DatarefMeta href "" "xpwebapi.api.DatarefMeta"
              click xpwebapi.api.APIObjMeta href "" "xpwebapi.api.APIObjMeta"

Container for XP Web API dataref meta data

Methods:

append_index –

Add index to list of requested indices for dataref of type array of value
last_indices –

Get list of last requested indices
save_indices –

Keep a copy of indices as requested

Attributes:

is_array (bool) –

Is dataref an array of values

is_array `property`

is_array: bool

Is dataref an array of values

append_index

append_index(i)

Add index to list of requested indices for dataref of type array of value

Note from Web API instruction/manual: If you subscribed to certain indexes of the dataref, they’ll be sent in the index order but no sparse arrays will be sent. For example if you subscribed to indexes [1, 5, 7] you’ll get a 3 item array like [200, 200, 200], meaning you need to remember that the first item of that response corresponds to index 1, the second to index 5 and the third to index 7 of the dataref. This also means that if you subscribe to index 2 and later to index 0 you’ll get them as [0,2]. So bottom line is — keep it simple: either ask for a single index, or a range, or all; and if later your requirements change, unsubscribe, then subscribe again.

last_indices

last_indices() -> list

Get list of last requested indices

save_indices

save_indices()

Keep a copy of indices as requested

MetaCacheBase

MetaCacheBase(api)


              flowchart TD
              xpwebapi.api.MetaCacheBase[MetaCacheBase]

              

              click xpwebapi.api.MetaCacheBase href "" "xpwebapi.api.MetaCacheBase"

Stores X-Plane Web API metadata in cache.

Must be "refreshed" each time a new connection is created. Must be refreshed each time a new aircraft is loaded (for new datarefs, commands, etc.) reload_cache() is provided in xpwebapi.

There is no faster structure than a python dict() for (name,value) pair storage.

Methods:

equiv –

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)
get –

Get meta data from cache by name
get_by_id –

Get meta data from cache by dataref or command identifier
get_by_name –

Get meta data from cache by name
load –

Load cache data
meta –

Create metadata from dictionary returned by X-Plane Web API.
save –

Saved cached data into file

Attributes:

count (int) –

Number of data in cache
has_data (bool) –

Cache contains data

count `property`

count: int

Number of data in cache

has_data `property`

has_data: bool

Cache contains data

equiv

equiv(ident) -> str | None

Return identifier/name equivalence, for diaply prupose in format 1234(path/to/object)

get

get(name) -> APIObjMeta | None

Get meta data from cache by name

get_by_id

get_by_id(ident: int) -> APIObjMeta | None

Get meta data from cache by dataref or command identifier

get_by_name

get_by_name(name) -> APIObjMeta | None

Get meta data from cache by name

load

load()

Load cache data

meta `classmethod`

meta(**kwargs) -> APIObjMeta

Create metadata from dictionary returned by X-Plane Web API.

save

save(filename)

Saved cached data into file

ValueCache

ValueCache(roundings: dict[str, int])

Utility class to round a dataref value and determine if it has changed.

XPLANE_API_VERSIONS


              flowchart TD
              xpwebapi.api.XPLANE_API_VERSIONS[XPLANE_API_VERSIONS]

              

              click xpwebapi.api.XPLANE_API_VERSIONS href "" "xpwebapi.api.XPLANE_API_VERSIONS"

API version number (string) versus X-Plane release number when that API version appeared for the first time

Core API

api

API

connected property

rest_url property

status property writable

status_str property

use_rest property writable

beacon_callback

connected

beacon_data

same_host

changed

command

path

dataref

path

auto_save

dataref_value

dataref

raw

no_decode

execute_command

command

duration

set_network

host

port

api

api_version

set_roundings

write_dataref

dataref

APIObjMeta

CONNECTION_STATUS

Cache

count property

has_data property

equiv

get

get_by_id

get_by_name

load

meta classmethod

save

Command

description property

ident property

meta property

valid property

execute

monitor

unmonitor

CommandCache

count property

has_data property

equiv

get

get_by_id

get_by_name

load

meta classmethod

save

CommandMeta

DATAREF_DATATYPE

Dataref

ident property

is_array property

is_monitored property

is_writable property

last_updated property

meta property

monitored_count property

valid property

value property writable

value_type property

dec_monitor

get_string_value

encoding

get_value

connected `property`

rest_url `property`

status `property` `writable`

status_str `property`

use_rest `property` `writable`

`connected`

`beacon_data`

`same_host`

`path`

`path`

`auto_save`

`dataref`

`raw`

`no_decode`

`command`

`duration`

`host`

`port`

`api`

`api_version`

`dataref`

count `property`

has_data `property`

meta `classmethod`

description `property`

ident `property`

meta `property`

valid `property`

count `property`

has_data `property`

meta `classmethod`

ident `property`

is_array `property`

is_monitored `property`

is_writable `property`

last_updated `property`

meta `property`

monitored_count `property`

valid `property`

value `property` `writable`

value_type `property`

`encoding`

`value`

`encoding`

count `property`

has_data `property`

meta `classmethod`

is_array `property`

count `property`

has_data `property`

meta `classmethod`