On Linux a Unix stream socket is created with the name /tmp/xplra-<user name>, where <user name> is the login account name of the user running X-Plane. On Windows a named pipe is created with the name \\.\pipe\xplra. The usual methods provided by the OS can be used to connect to these.

The protocol is a binary protocol. The client initiates commands which are executed by the plugin. Each command is a byte followed by the arguments of the command. The plugin responds with a result code, which is also a byte, which may be followed by the rest of the reply, e.g. the data queried or a parameter to an error code.

Types of protocol data elements

The protocol's basic data elements are: 8-, 16- and 32-bit signed and unsigned integers, single and double precision floating point values and strings. The endianness of the values is that of the host operating system.

Strings are encoded as a variable-length length followed by as many bytes making up the actual contents of the string. The variable-length length consists of bytes whose most-significant bit is 1, if there is another byte and 0 for the last byte. The first byte contains the least significant 7 bits of the length, the second byte contains bits 7-13, and so on. Some examples:

12 => 0x0c
123 => 0x7b
128 => 0x80 0x01
210 => 0xd2 0x01
7345 => 0xb1 0x39
90000 => 0x90 0xbf 0x05

Data type codes

Each dataref of X-Plane has a certain data type, and some datarefs can represent their values in multiple data types. Because of this ambiguity and the fact that users should know the data type anyway, especially when using a strongly typed language, the type should be sent with the dataref name in commands that refer to one or more datarefs.

Each data type is represented as an 8-bit unsigned integer, whose possible values are given in the table below:

Data type	Value	Constant name
32-bit signed integer	0x01	TYPE_INT
single-precision floating-point value	0x02	TYPE_FLOAT
double-precision floating-point value	0x03	TYPE_DOUBLE
array of single-precision floating-point values	0x11	TYPE_FLOAT_ARRAY
array of 32-bit signed integers	0x12	TYPE_INT_ARRAY
array of 8-bit unsigned integers (bytes)	0x13	TYPE_BYTE_ARRAY

The constant name is the name used in both client APIs to identify the given type.

The scalar data types are encoded as in the following table:

Data type constant	Encoding
TYPE_INT	a 32-bit (4-byte) signed integer
TYPE_FLOAT	a 32-bit (4-byte) IEEE 754 single-precision floating point value
TYPE_DOUBLE	a 64-bit (8-byte) IEEE 754 double-precision floating point value

The contents of an array is encoded as a sequence of values of the items' type. It is usually preceded by a 32-bit signed integer denoting the number of items and sometimes also by another 32-bit signed integer denoting the offset into the array.

Result codes

The first byte of the reply message to each command is a result code. If the command could be executed properly, it is RESULT_OK followed by the results of the command if any, otherwise it is another code signifying some error. Most error codes are followed by no further data, but RESULT_UNKNOWN_DATAREF may be followed by an index if a multi-dataref request is issued.

The table summarizes the error codes:

Meaning	Value	Constant name
Success, everything is OK	0x00	RESULT_OK
Invalid command	0x01	RESULT_INVALID_COMMAND
Unknown dataref	0x02	RESULT_UNKNOWN_DATAREF
Invalid data type	0x03	RESULT_INVALID_TYPE
Invalid length	0x04	RESULT_INVALID_LENGTH
Invalid offset	0x05	RESULT_INVALID_OFFSET
Invalid count	0x06	RESULT_INVALID_COUNT
Invalid ID	0x07	RESULT_INVALID_ID
Invalid duration	0x08	RESULT_INVALID_DURATION
Other error	0xff	RESULT_OTHER_ERROR

Limits

Certain parameters have limits, which are summarized in the following table:

Description	Limit
maximal number of array items	2048
maximal number of datarefs in a multi-dataref operation	1024
maximal duration of a message	5 minutes
maximal number of hotkeys that can be registered	128

Commands

This section describes the commands of the protocol with their parameters and the possible replies. Each command is represented by an 8-bit unsigned value, which is the first byte of the message. The table below summarizes the commands with their command byte and constant names:

Description	Command byte	Constant Name
Query the value of a single dataref	0x01	COMMAND_GET_SINGLE
Set the value of a single dataref	0x02	COMMAND_SET_SINGLE
Query the values of multiple datarefs	0x03	COMMAND_GET_MULTI
Set the values of multiple datarefs	0x04	COMMAND_SET_MULTI
Register a multi-dataref query	0x11	COMMAND_REGISTER_GET_MULTI
Unregister a multi-dataref query	0x12	COMMAND_UNREGISTER_GET_MULTI
Execute a registered multi-dataref query	0x13	COMMAND_EXECUTE_GET_MULTI
Register a multi-dataref update request	0x21	COMMAND_REGISTER_SET_MULTI
Unregister a multi-dataref update request	0x22	COMMAND_UNREGISTER_SET_MULTI
Execute a registered multi-dataref update request	0x23	COMMAND_EXECUTE_SET_MULTI
Query the versions of X-Plane, XPLM and XPLRA	0x31	COMMAND_GET_VERSIONS
Reload the plugins in X-Plane	0x32	COMMAND_RELOAD_PLUGINS
Save the current situation	0x33	COMMAND_SAVE_SITUATION
Show a message in X-Plane's window	0x41	COMMAND_SHOW_MESSAGE
Register hotkeys to be listened to	0x51	COMMAND_REGISTER_HOTKEYS
Query the sate of the registered hotkeys	0x52	COMMAND_QUERY_HOTKEYS
Unregister the previously registered hotkets	0x53	COMMAND_UNREGISTER_HOTKEYS

The GET_SINGLE command

This command can be used to query the value of a single dataref. Such a data can either be a scalar (integer, float or double) or an array of floats, integers or bytes.

The format of the command is the following:

Type	Description
byte	0x01 (COMMAND_GET_SINGLE)
dataref_query_info	information about the dataref to query

dataref_query_info has the following format for scalar types:

Type	Description
string	the name of the dataref to query
byte	the type of the dataref, one of the TYPE_XXX constants

dataref_query_info has the following format for array types:

Type	Description
string	the name of the dataref to query
byte	the type of the dataref, one of the TYPE_XXX_ARRAY constants
32-bit signed integer	the number of items to query, -1 to query all items
32-bit signed integer	the offset of the data within the array to query

If the command is executed successfully, the reply has the following format for scalar types:

Type	Description
byte	0x00 (RESULT_OK)
dataref_value	the value of the dataref

dataref_value is encoded as follows for scalar types:

Type	Description
scalar type	the value of the dataref

dataref_value is encoded as follows for array types:

Type	Description
32-bit signed integer	n=the number of items returned
n*type of the items	the data items themselves

In case of an error:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_UNKNOWN_DATAREF	the dataref with the given name was not found
RESULT_INVALID_TYPE	an unknown type code was given
RESULT_INVALID_LENGTH	the length given for an array is too large
RESULT_INVALID_OFFSET	the offset given for an array is negative

The SET_SINGLE command

This command can be used to set the value of a single dataref. Such a data can either be a scalar (integer, float or double) or an array of floats, integers or bytes.

The format of the command is the following for scalar values:

Type	Description
byte	0x02 (COMMAND_SET_SINGLE)
dataref_update_info	information about the dataref to set and the value itself

dataref_update_info has the following format for scalar values:

Type	Description
string	the name of the dataref to set
byte	the type of the dataref, one of the TYPE_XXX constants
dataref's type	the value to set

dataref_update_info has the following format for array values:

Type	Description
string	the name of the dataref to set
byte	the type of the dataref, one of the TYPE_XXX_ARRAY constants
32-bit signed integer	n=the number of items to set
32-bit signed integer	the offset from which to set the values
n*type of the items	the actual values of the array

If the command is executed successfully, the reply has the following format for scalar types:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_UNKNOWN_DATAREF	the dataref with the given name was not found
RESULT_INVALID_TYPE	an unknown type code was given
RESULT_INVALID_LENGTH	the length given for an array is too large or not positive
RESULT_INVALID_OFFSET	the offset given for an array is negative

The GET_MULTI command

This command can be used to query the values of several datarefs in one call. It is encoded as follows:

Type	Description
byte	0x03 (COMMAND_GET_MULTI)
32-bit unsigned integer	n=the number of datarefs to query
n*dataref_query_info	information about the datarefs to query.

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)
n*dataref_value	the values of the datarefs

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code
32-bit unsigned integer	if the error code is RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found

The following error codes may be returned:

Code	Meaning
RESULT_UNKNOWN_DATAREF	the dataref with the given name was not found
RESULT_INVALID_TYPE	an unknown type code was given
RESULT_INVALID_LENGTH	the length given for an array is too large
RESULT_INVALID_OFFSET	the offset given for an array is negative
RESULT_INVALID_COUNT	the number of datarefs was either 0 or too large

The SET_MULTI command

This command can be used to set the values of several datarefs in one call. It is encoded as follows:

Type	Description
byte	0x04 (COMMAND_SET_MULTI)
32-bit unsigned integer	n=the number of datarefs to set
n*dataref_update_info	information about the datarefs to set

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code
32-bit unsigned integer	if the error code is RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found

The following error codes may be returned:

Code	Meaning
RESULT_UNKNOWN_DATAREF	the dataref with the given name was not found
RESULT_INVALID_TYPE	an unknown type code was given
RESULT_INVALID_LENGTH	the length given for an array is too large or not positive
RESULT_INVALID_OFFSET	the offset given for an array is negative
RESULT_INVALID_COUNT	the number of datarefs was either 0 or too large

The REGISTER_GET_MULTI command

This command can be used to register a multi-dataref query. A multi-dataref query is a list of datarefs that are queried together. The query will be associated with an identifier that can be used later to refer to the query when actually querying the values or when unregistering it. The identifier is unique only for the client connection and among the multi-dataref queries.

Type	Description
byte	0x11 (COMMAND_REGISTER_GET_MULTI)
32-bit unsigned integer	n=the number of datarefs to query
n*dataref_query_info	information about the datarefs to query.

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)
32-bit unsigned integer	the identifier of the registered query

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_INVALID_TYPE	an unknown type code was given
RESULT_INVALID_LENGTH	the length given for an array is too large
RESULT_INVALID_OFFSET	the offset given for an array is negative
RESULT_INVALID_COUNT	the number of datarefs was either 0 or too large

The UNREGISTER_GET_MULTI command

This command can be used to unregister a previously registered multi-dataref query.

Type	Description
byte	0x12 (COMMAND_UNREGISTER_GET_MULTI)
32-bit unsigned integer	the identifier of the query to unregister

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_INVALID_ID	an identifier was given that is not associated with any registered query

The EXECUTE_GET_MULTI command

This command can be used to execute a previously registered multi-dataref query.

Type	Description
byte	0x13 (COMMAND_EXECUTE_GET_MULTI)
32-bit unsigned integer	the identifier of the query to execute

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)
n*dataref_value	the values of the datarefs, n is the number of them

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code
32-bit unsigned integer	if the error code is RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found

The following error codes may be returned:

Code	Meaning
RESULT_UNKNOWN_DATAREF	the dataref with the given name was not found
RESULT_INVALID_ID	an identifier was given that is not associated with any registered query

The REGISTER_SET_MULTI command

This command can be used to register a multi-dataref update. A multi-dataref update is a list of datarefs that are updated together with values supplied for each update. The update will be associated with an identifier that can be used later to refer to the update when actually updating the values or when unregistering it. The identifier is unique only for the client connection and among the multi-dataref updates.

Type	Description
byte	0x21 (COMMAND_REGISTER_SET_MULTI)
32-bit unsigned integer	n=the number of datarefs to query
n*dataref_query_info	information about the datarefs to update (this is dataref_query_info, because the format is the same, since we don't supply any values)

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)
32-bit unsigned integer	the identifier of the registered query

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_INVALID_TYPE	an unknown type code was given
RESULT_INVALID_LENGTH	the length given for an array is too large or not positive
RESULT_INVALID_OFFSET	the offset given for an array is negative
RESULT_INVALID_COUNT	the number of datarefs was either 0 or too large

The UNREGISTER_GET_MULTI command

This command can be used to unregister a previously registered multi-dataref update.

Type	Description
byte	0x22 (COMMAND_UNREGISTER_SET_MULTI)
32-bit unsigned integer	the identifier of the update to unregister

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_INVALID_ID	an identifier was given that is not associated with any registered update

The EXECUTE_SET_MULTI command

This command can be used to execute a previously registered multi-dataref update.

Type	Description
byte	0x23 (COMMAND_EXECUTE_SET_MULTI)
32-bit unsigned integer	the identifier of the update to execute
n*dataref_value	the values

In case of success, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code
32-bit unsigned integer	if the error code is RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found

The following error codes may be returned:

Code	Meaning
RESULT_UNKNOWN_DATAREF	the dataref with the given name was not found
RESULT_INVALID_ID	an identifier was given that is not associated with any registered query

The GET_VERSIONS command

This command can be used to query the versions of X-Plane, XPLM and XPLRA itself.

Type	Description
byte	0x31 (COMMAND_GET_VERSIONS)

The reply is encoded the following way (it shall never fail):

Type	Description
byte	0x00 (RESULT_OK)
32-bit signed integer	the version of X-Plane. For 10.20r1 it is 10201.
32-bit signed integer	the version of XPLM. For 2.10 it is 210.
32-bit signed integer	the version of XPLRA. For 0.1 it is 10.

The RELOAD_PLUGINS command

This command can be used to reload the plugins in X-Plane. This is useful for debugging.

Type	Description
byte	0x32 (COMMAND_RELOAD_PLUGINS)

The reply is encoded the following way (it shall never fail):

Type	Description
byte	0x00 (RESULT_OK)

The SAVE_SITUATION command

This command can be used to save the current situation into a file. It is available only on X-Plane 10 or later.

Type	Description
byte	0x33 (COMMAND_SAVE_SITUATION)
string	the path of the file to save the situation into, relative to the X-Plane directory

If successful, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply is the following (no error could be produced yet, but it might fail).

Type	Description
byte	0xff (RESULT_OTHER_ERROR)

The GET_VERSIONS command

This command can be used to query the versions of X-Plane, XPLM and XPLRA itself.

Type	Description
byte	0x31 (COMMAND_GET_VERSIONS)

The reply is encoded the following way (it shall never fail):

Type	Description
byte	0x00 (RESULT_OK)
32-bit signed integer	the version of X-Plane. For 10.20r1 it is 10201.
32-bit signed integer	the version of XPLM. For 2.10 it is 210.
32-bit signed integer	the version of XPLRA. For 0.1 it is 10.

The SHOW_MESSAGE command

This command can be used to show a message in a window to the user. The window is a single line window around the top 1/3rd of the screen. It can be moved and resized by mouse actions. If a message is being displayed when this command is issued, that message will be replaced by the new one.

Type	Description
byte	0x41 (COMMAND_SHOW_MESSAGE)
string	the message to show
float	the duration of the message in seconds

If successful, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_INVALID_DURATION	the duration is too large

The REGISTER_HOTKEYS command

This command can be used to register a set of hotkeys to be monitored. If any other hotkeys have been registered by the current client previously, they are forgotten.

Type	Description
byte	0x51 (COMMAND_REGISTER_HOTKEYS)
32-bit unsigned integer	n=the number of the hotkeys
n * 16-bit unsigned integer	the codes of the hotkeys

The lower-byte of a hotkey code is the same as the X-Plane virtual key code. The upper byte is a logical OR of zero or more modifiers:

Value	Description	Constant name
0x0100	Shift modifier	HOTKEY_MODIFIER_SHIFT
0x0200	Control modifier	HOTKEY_MODIFIER_CONTROL

If successful, the reply is the following:

Type	Description
byte	0x00 (RESULT_OK)

If an error was encountered, the reply has the following format:

Type	Description
byte	the error code

The following error codes may be returned:

Code	Meaning
RESULT_INVALID_LENGTH	too many hotkeys were given

The QUERY_HOTKEYS command

This command can be used to query which hotkeys have been pressed since the last query.

Type	Description
byte	0x52 (COMMAND_QUERY_HOTKEYS)

The reply is the following:

Type	Description
byte	0x00 (RESULT_OK)
32-bit unsigned integer	n = the number of hotkeys registered
n * 8-bit unsigned integer	each byte is 0 or 1 depending whether the corresponding hotkeys was pressed or not. The value at index i corresponds to the hotkey code at index i in the array passed with COMMAND_REGISTER_HOTKEYS

The UNREGISTER_HOTKEYS command

This command can be used to unregister a previously registered set of hotkeys to be monitored.

Type	Description
byte	0x53 (COMMAND_UNREGISTER_HOTKEYS)

The reply is the following:

Type	Description
byte	0x00 (RESULT_OK)