diff --git a/docs/Button.md b/docs/Button.md index 98226b26..6ba2e5db 100644 --- a/docs/Button.md +++ b/docs/Button.md @@ -61,15 +61,24 @@ The button *Representation* page describes attributes specific to the *feedback* (In the picture above, this refer to the yellow part of the definition.) -A Button has a value that is maintained and used mainly for representation. +A Button has a value that is maintained and used mainly for its representation. + +The value of a button can come from two sources: + +- The simulator (i.e. some variable or parameter used and controlled by the simulator) +- The internal state of the button (read below) The following attributes are used to determine a button’s value: `dataref` : A single dataref value. -`formula`: An expression that contains variables and mathematical operations to combine and compute a value +`formula`: An expression that contains variables, including datarefs, and mathematical operations to combine and compute a value + +`multi-datarefs`: A list of two or more datarefs. The values of all datarefs in the list will be returned as the value of the button, although in this case, the value will be a composite value. The representation that uses such a specific value will know how to use each individual component of the composite value. + +## Value from the Simulator -`multi-datarefs`: A list of two or more datarefs. The values of all datarefs in the list will be returned. +When the value of a button is computed from one or more values coming from the simulator, Cockpitdecks will request the values from the simulator, and each time one of these values changes, Cockpitdecks will notify the button of the changes so that it can adjust its representation. ## Button State diff --git a/docs/Cockpit.md b/docs/Cockpit.md index 102a3f8c..7bf8b06e 100644 --- a/docs/Cockpit.md +++ b/docs/Cockpit.md @@ -1,13 +1,21 @@ -The Cockpit is the *Maestro* of the Cockpitdecks application. +Cockpitdecks is an application that connect decks to the X-Plane flight simulator. On one side, the application scans for connected decks and prepare them for use with X-Plane. On the other side, Cockpitdecks connects to X-Plane to issue instructions and listen to changes and reflect those changes on the deck device if it allows it. -It starts up the entire Cockpitdecks application. It establishes connection to the simulator, scans for existing decks connected to the computer, and load the aircraft configuration files. It listen to interactions that occur on the decks and listen to simulator changes to reflect deck statuses. It also monitors which aircraft is currently loaded in the simulator, and if the user changes aircraft, it loads the new configuration if any. +To determine what to display on decks, which commands to issue to the simulator, etc. Cockpitdecks reads a set of configuration files on startup. -# Aircraft Configuration +Configuration files are specific to an aircraft. Commands are different on a Cesna and on an Airbus. Things to display are different as well. That’s why configuration files are located in the folder of the aircraft being used. Numerous other software like X-Camera proceed in a similar way, locating their aircraft specific configuration there as well. + +The Cockpit is the *Maestro* component of the Cockpitdecks application. -Decks are particular to one aircraft. All files necessary to Cockpitdecks are located in a single folder named `deckconfig` that is found in the folder of the X-Plane aircraft currently being used. In that folder, Cockpitdecks will discover all decks connected to the system and available to it. +It starts up the entire Cockpitdecks application. It establishes connection to the simulator, scans for existing decks connected to the computer, and load the aircraft configuration files. It listen to interactions that occur on the decks and listen to simulator changes to reflect deck statuses. It also monitors which aircraft is currently loaded in the simulator, and if the user changes aircraft, it loads the new configuration if any. + +The following pages describe the necessary configuration files, their location and organisation, and their content. Configuration files are organised in structured folders, and this structure is explained as well. All configuration files for Cockpitdecks are *Yaml-formatted files*. Yaml file contains a structured list of (name, value) pairs. The name is referred to as an *attribute*. The *value* can be almost anything: A number, a string, a list of things, or a list of other attributes. +# Aircraft Configuration + +Decks are particular to one aircraft. All files necessary to Cockpitdecks are located in a single folder named `deckconfig` that is found in the folder of the X-Plane aircraft currently being used. In that folder, Cockpitdecks will find all its configuration files. + # The `deckconfig` Folder The overall structure of the files and sub-folders inside the `deckconfig` folder is as follow: @@ -44,16 +52,16 @@ The overall structure of the files and sub-folders inside the `deckconfig` folde The `deckconfig` folder contains the following files and sub-folders: -| Name | Description | -| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| config.yaml | Main configuration file | -| secret.yaml | Serial numbers of decks used by Cockpitdecks | -| resources | Resource files used by this configuration. Resources are icons, fonts, images, etc. | -| layout(s) | A Layout is a folder that contains what is displayed on a deck. There can be as many Layout Folder as necessary for this aircraft. All remaining folders in the `deckconfig`folder are layout folders. There usually is one Layout folder per deck. | +| Name | Description | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `config.yaml` | Main configuration file | +| `secret.yaml` | Serial numbers of decks used by Cockpitdecks | +| resources | Resource files used by this configuration. Resources are icons, fonts, images, etc. | +| layout(s) | A Layout is a folder that contains what is displayed on a deck. There can be as many Layout Folder as necessary for this aircraft. All remaining folders in the `deckconfig`folder are layout folders. There usually is one Layout folder per deck. | # `config.yaml` File -The file named `config.yaml` in the `deckconfig` folder contains declarations for each [[Deck|deck]] that will be used and global, aircraft-level attributes. +The file named `config.yaml` in the `deckconfig` folder it the main configuration file, It contains declarations for each [[Deck|deck]] that will be used, and global, aircraft-level attributes. ```yaml # Definition of decks for Toliss A321 @@ -77,7 +85,7 @@ cockpit-color: lightblue ## Attributes -The parameters apply to all decks for the given aircraft. Each individual deck will have the possibility to redefine these values if necessary. +The following attributes apply to all decks for the given aircraft. Each individual deck will have the possibility to redefine these values if necessary. | Attribute | Definition | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -89,7 +97,7 @@ The parameters apply to all decks for the given aircraft. Each individual deck w | `default-*` | Name of default values of several parameters, defined at the aircraft-level. These values will be used for all missing values. They can be raffined at Layout and Page level if necessary.

If no aircraft-level global parameter values are not provided, Cockpitdecks will use its own internal default values. | | **decks** | A list of [[Deck]] structure, one per deck. | -Yaml allow for other attributes in the file. They are ignored by Cockpitdecks. You may include other attributes like aircraft name, ICAO code, descriptions, notes, even change log of your file. +Yaml allow for other attributes in the file. They are ignored by Cockpitdecks. You may include other attributes like aircraft name, ICAO code, descriptions, notes, even change log of your file. Comments are also allowed in Yaml files. # `secret.yaml` File @@ -109,6 +117,8 @@ XPLive: AAA0000000000000000000A0000 Resources are fonts, icons, other images, wallpapers, documentation, and texts used and related to that aircraft. +Usually, the resources folder contains the following sub-folders: + | Folder | Content | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | icons | Folder containing all icon images for that aircraft. Images should be in JPEG or PNG format. Typical icon size is 256 × 256 pixels, RGB(A). Icons are named after their file name without the extension. | @@ -121,3 +131,7 @@ Resources are fonts, icons, other images, wallpapers, documentation, and texts u Next to the the above *resources* folder, there will be one folder per Layout for a deck. [[Layout|Layout folders]] are explained separately. + +# Decks + +One of the most important attributes in this first configuration file is the `decks` attribute which lists all [[cockpitdecks-docs/docs/Deck|Deck]] Cockpitdecks will use. diff --git a/docs/Extending/Web Decks.md b/docs/Extending/Web Decks.md index 426b0d0e..f53898fa 100644 --- a/docs/Extending/Web Decks.md +++ b/docs/Extending/Web Decks.md @@ -1,5 +1,7 @@ In addition to real physical decks, Cockpitdecks offers *Web Decks* rendered in a browser window. +Web Decks were first developed as a tool to speed up deck page creation, but Web Decks turned out to be fast and available everywhere, in particular on tablets. + ![[virtualdecks.jpg]] A Web Deck behaves like their physical counterparts, with limitations inherent to presentation in a browser window. In a nutshell, a web deck has an optional background image (or a uniform background color), and buttons laid over it. Buttons can be of four main types: diff --git a/docs/Installation.md b/docs/Installation.md index 44ac816c..832fd097 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -21,7 +21,7 @@ In particular, the X-Plane Cockpitdecks Helper plugin uses and requires the late ## Enable X-Plane UDP > [!NOTE] X-Plane 12 and UDP -> X-Plane 12 appears to disable UDP networking initially. Check Settings -> Network page, and make sure “Accept incoming connections” is enabled. +> X-Plane 12 appears to disable UDP networking on new installations. Check Settings -> Network page, and make sure “Accept incoming connections” is enabled.   (See X-Plane UDP manual. Will provide information here later.) @@ -59,21 +59,21 @@ To circumvent this, Cockpitdecks provides a small python plugin called the Cockp If not installed, some of the commands inside Cockpitdecks will work properly. -Cockpitdecks Helper plugin is an _in-process_ plugin, running inside X-Plane, while Cockpitdecks is an _out-of-process_ executable. +Cockpitdecks Helper plugin is an _in-process_ plugin, running inside X-Plane, while Cockpitdecks is an _out-of-process_ executable running independently of X-Plane. ### Why an Additional Plugin? #### Long command execution -Some commands cannot be executed directly through UDP. For exemples, commands that have a start and an end cannot be started or ended though UDP. It is an X-Plane UDP limitation. +Some commands cannot be executed directly through UDP. For exemples, commands that have a *start* and an *end* cannot be started or ended though UDP. It is an X-Plane UDP limitation. To execute long press commands, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 PythonPlugins folder. #### String Datarefs -X-Plane UDP only allows to fetch dataref values one by one. Retrieving a string is a tedious process. +X-Plane UDP only allows to fetch dataref values one by one. Retrieving a string is a tedious process Bea cause each individual character has to be fetched. -To collect string-typed datarefs, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 PythonPlugins folder. +To collect string-typed datarefs, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 PythonPlugins folder. It collects the entire string and then broadcasts it as a whole string, not individual characters. See [[String Datarefs]] for details about this. @@ -95,7 +95,7 @@ To install both services described above, copy the plugin file to: ... /X-Plane 12/resources/plugins/PythonPlugins/PI_cockpitdecks.py ``` -and ask XPPython3 plugin to reload the scripts. +and ask XPPython3 plugin to reload its scripts. ## Install Aircraft Specific `deckconfig` Folders diff --git a/docs/Usage.md b/docs/Usage.md index a3a9abd4..ddb246f7 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -6,20 +6,20 @@ First, you have to completely stop (quit completely) original manufacturer deck # Adjust `environment.yaml` -Cockpitdecks uses a single configuration file, called the Cockpitdecks environment file, to define a few elements that cannot easily be guessed. Cockpitdecks provides a configuration file that is suitable for single computer installation. You must, however, adjust at least the simulator folder path. +Cockpitdecks uses a configuration file, called the Cockpitdecks environment file, to define a few elements that cannot easily be guessed. Cockpitdecks provides a environment file that is suitable for single computer installation. You must, however, adjust at least the simulator folder path. -| Variable | Definiton | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `SIMULATOR_NAME` | Name of simulator to use. Currently, only X-Plane is a valid value. | -| `SIMULATOR_HOME` | Home directory of X-Plane on the computer where Cockpitdecks runs. If X-Plane is installed on a remote host, `SIMULATOR_HOME` must be `None`. | -| `SIMULATOR_HOST` | Hostname or IP address where *X-Plane* runs. Defaults to local host. | -| `APP_HOST` | Tuple (Hostname or IP address, port) where *Cockpitdecks* application runs. If specified through operating system environment variables, use (**APP_HOST** and **APP_PORT**). Default to (local host, 7777). | -| `API_PORT` | X-Plane (12.1.1 and above) where REST API runs. Default to `8086`. | -| `API_PATH` | X-Plane (12.1.1 and above) where REST API: X-Plane API root path. Currently default to `/api/v1`. | -| `COCKPITDECKS_EXTENSION_PATH` | List of paths where to search for Cockpitdecks extensions | -| `COCKPITDECKS_EXTENSION_NAME` | List of python package names that contains Cockpitdecks extensions | +| Variable | Definiton | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `SIMULATOR_NAME` | Name of simulator to use. Currently, only X-Plane is a valid value. | +| `SIMULATOR_HOME` | Home directory of X-Plane on the computer where Cockpitdecks runs. If X-Plane is installed on a remote host, `SIMULATOR_HOME` must be `None`. | +| `SIMULATOR_HOST` | Hostname or IP address where *X-Plane* runs. Defaults to local host. | +| `APP_HOST` | Tuple (Hostname or IP address, port) where *Cockpitdecks* application runs. If specified through operating system environment variables, use (**APP_HOST** and **APP_PORT**). Default to (localhost, 7777). | +| `API_PORT` | X-Plane (12.1.1 and above) where REST API runs. Default to `8086`. | +| `API_PATH` | X-Plane (12.1.1 and above) where REST API: X-Plane API root path. Currently default to `/api/v1`. | +| `COCKPITDECKS_EXTENSION_PATH` | List of paths where to search for Cockpitdecks extensions | +| `COCKPITDECKS_EXTENSION_NAME` | List of python package names that contains Cockpitdecks extensions | -In addition, there is a operating system environment variable `COCKPITDECKS_PATH` that holds folders where Cockpitdecks will look for aircraft configurations. +In addition, there is a operating system environment variable `COCKPITDECKS_PATH` that lists folder paths where Cockpitdecks will look for aircraft configurations. If you do not want to modify the Cockpitdecks-provided `environ.yaml` file, you always can supply one on the command line with the `—-env` flag. @@ -27,6 +27,13 @@ The set of global parameters provided in the `environ.yaml` file is called the C Cockpitdecks provides two templates configuration files for local and remote use. +The minimal environment file if everything runs locally is + +``` +SIMILATOR_NAME: X-Plane +SIMULATOR_HOME: +``` + # Start Cockpitdecks Currently, Cockpitdecks only offers a command-line interface to be executed in a shell window. @@ -89,11 +96,13 @@ Make sure the configuration file is setup. When everything is run on the same co cockpitdecks-cli ``` -Cockpitdecks will immediately start in demonstration mode and listen for X-Plane interaction. If Cockpitdecks detects tht X-Plane is running, finds that an aircraft is loaded, and that a Cockpitdecks `deckconfig` folder exists in the folder of that aircraft, Cockpitdecks will load this configuration. +Cockpitdecks will immediately start in demonstration mode and listen for X-Plane interaction. If Cockpitdecks detects that X-Plane is running, finds that an aircraft is loaded, and that a Cockpitdecks `deckconfig` folder exists in the folder of that aircraft, Cockpitdecks will load that configuration. If no configuration is found, Cockpitdecks will listen and interpret X-Plane data but will not load a new configuration. -This mode is fully automatic, Cockpitdecks always attempts to load the current aircraft `deckconfig` configuration, if present. Similarly, the XPPython3 plugin, if installed, will load the corresponding new configuration as well. +This mode is fully automatic. If X-Plane is stoped or later restarted, Cockpitdecks will notice it and either wait idle that X-Plane is started, and if X-Plane is running, Cockpitdecks will attempt to load the aircraft configuration, if any. + +Cockpitdecks always attempts to load the current aircraft `deckconfig` configuration, if present. Similarly, the XPPython3 plugin, if installed, will load the corresponding new configuration as well. ## Cockpidecks and X-Plane Run on Different Computer diff --git a/docs/index.md b/docs/index.md index 44a0218f..9c663be8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,14 @@ # Welcome to Cockpitdecks -Cockpitdecks is an application, a set of python scripts created to use external physical decks connected to a computer with X-Plane flight simulator. +Cockpitdecks is an application to use *decks* connected to a computer with X-Plane flight simulator. -External decks include the following make and models: +The following make and models have been tested and work with Cockpitdecks: -- Elgato Stream Deck small, Mk.2, XL, Plus, and Neo -- Loupedeck LoupedeckLive -- Berhinger X-Touch Mini +- [Elgato Stream Deck](https://www.elgato.com/us/en/s/welcome-to-stream-deck) small, Mk.2, XL, Plus, and Neo, +- [Loupedeck LoupedeckLive](https://loupedeck.com/products/loupedeck-live/) +- [Berhinger X-Touch Mini](https://www.behringer.com/product.html?modelCode=0808-AAF) -There also are Web Decks, a simulator of any of the above deck in a web page, in the context of this application. Web Decks were first developed as a tool to speed up deck page creation, but Web Decks turned out to be fast and available everywhere, in particular on tablets. Yes, you read it, you can now have any of the above deck, for free, on a tablet, to use with X-Plane flight simulator. +There also are Web Decks, an emulator of the above decks in a web page, in the context of this application. Yes, you read it, you can now have any of the above deck, for free, on a tablet, to use with X-Plane flight simulator. Cockpitdecks can run on the same computer as X-Plane, or a remote computer, network-connected to X-Plane.