diff --git a/docs/Extending/Internals/Deck Internals.md b/docs/Extending/Internals/Deck Internals.md index 1e3d49ba..bc93afd5 100644 --- a/docs/Extending/Internals/Deck Internals.md +++ b/docs/Extending/Internals/Deck Internals.md @@ -27,11 +27,11 @@ In the overall software organisation of Cockpitdecks, everything related to deck The `decks` folder is organized as follow: (between parenthesis, the content of the folder or file.) -``` hl_lines="1 5" +``` deckconfig ⊢ resources ⊢ decks - + cockpitdecks/decks ⊢ resources << accessory files ⊢ templates << Jinja2 templates diff --git a/docs/Installation.md b/docs/Installation.md new file mode 100644 index 00000000..a83f6b6d --- /dev/null +++ b/docs/Installation.md @@ -0,0 +1,105 @@ +![[installer.jpg|600]] + +Cockpitdecks is a regular python application and will run with python 3.10, or newer. + +It is recommended to create a dedicated environment and run Cockpitdecks within that environment. + +# X-Plane *!* + +Cockpitdecks is a modern software that takes benefit from all available possibilities. While being developed, it is constantly updated to use the latest packages and features. + +Therefore, Cockpitdecks will work better with the latest production release of X-Plane. It may not work properly, or some feature may not be available when using older versions of X-Plane. We do not have the engineering resources to maintain working versions of Cockpitdecks for all versions of X-Plane. While most features should still work in X-Plane 11, they were never tested, and we will not provide any support to make it work on older release. + +Same occurs with aircrafts. Aircrafts are pieces of software that are regularly updated. It is a good practice to include the X-Plane and aircraft version information as comments in the `deckconfig` files, to precise which version of X-Plane or an aircraft is required to run properly. + +As a practical example, X-Plane recently opened access to internal data through a new channel: [A Web REST API access](https://developer.x-plane.com/article/x-plane-web-api/). This is offered in X-Plane release 12.1.1 or newer. Immediately, Cockpitdecks has taken benefit from this new, simplified mean to access internal values. + +It is good practice to maintain the software you use to the latest, production version. Cockpitdecks is no exception to this advise. + +In particular, the X-Plane Cockpitdecks Helper plugin uses and requires the latest version of [XPPython3](https://xppython3.readthedocs.io/en/latest/index.html) plugin to work. This plugin itself requires X-Plane 12 and recent version of X-Plane SDK. Cockpitdecks Helper plugin is strictly not required to run Cockpitdecks but some features will not work without it. + +## 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. +  +(See X-Plane UDP manual. Will provide information here later.) + +# Install Cockpitdecks Application + +## Install Cockpitdecks Software + +Create a new python environment and activate it. In that environment, issue the pip install command: + +```sh +pip install 'cockpitdecks[weather,streamdeck] @ git+https://github.com/devleaks/cockpitdecks.git' +``` + +Valid installable extras (between the `[` `]`, comma separated, no space) are: + +| Extra | Content | +| ------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `weather` | To load special iconic representation for weather. These icons sometimes fetch information outside of X-Plane. Recommended. | +| `streamdeck` | For Elgato Stream Deck decks | +| `loupedeck` | For Loupedeck LoupedeckLive, LoupedeckLive.s and Loupedeck CT devices | +| `xtouchmini` | For Berhinger X-Touch Mini device | +| `development` | For developer only, add testing packages and python types | + +## Install Cockpitdecks Helper Plugin + +> [!WARNING] Cockpitdecks X-Plane Helper Plugin +> You can do this step later, but some functions will not work or be available inside Cockpitdecks. + +X-Plane UDP has some shortcomings that prevent some operations with decks. + +To circumvent this, Cockpitdecks provides a small python plugin called the Cockpitdecks Helper plugin, that need to be installed into X-Plane. The Cockpitdecks Helper plugin will execute some instructions on behalf of the Cockpitdecks application. Cockpitdecks Helper plugin just need to be installed and will provide its services to Cockpitdecks. + +If not installed, some of the commands inside Cockpitdecks will work properly. + +#### 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. + +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. + +To collect string-typed datarefs, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 PythonPlugins folder. + +See [[String Datarefs]] for details about this. + +#### Cockpitdecks Helper Plugin Installation + +Cockpitdecks Helper Plugin is written in the python language. So it needs the [XPPython3](https://xppython3.readthedocs.io/) X-Plane plugin installed. XPPython3 plugin allow for execution of python code inside X-Plane. + +Cockpitdecks XPPython3 plugin is located in the + +```sh +< Cockpitdecks-installed-code > /cockpitdecks/resources/xppython3-plugins +``` + +folder in the source code. There is a single file. + +To install both services described above, copy the plugin file to: + +```shell +... /X-Plane 12/resources/plugins/PythonPlugins/PI_cockpitdecks.py +``` + +and ask XPPython3 plugin to reload the scripts. + +## Install Aircraft Specific `deckconfig` Folders + +Duane, a Cockpitdecks aficionado has realized several configurations for several aircrafts. + +You can [find them here](https://github.com/dlicudi/cockpitdecks-configs), download them and install them in your aircraft folder. + +Cockpitdecks `deckconfig` folder must be placed in the folder of the X-Plane aircraft to be found by Cockpitdecks or the Cockpitdecks Helper plugin. + +``` +/Aircraft/Extra Airicraft/Toliss A321/deckconfig +``` + +Now you are ready to [[Usage|start Cockpitdecks]]. diff --git a/docs/Resources.md b/docs/Resources.md index e99d0a49..e9b77a02 100644 --- a/docs/Resources.md +++ b/docs/Resources.md @@ -56,6 +56,10 @@ Internally, Cockpitdecks use 256 pixel icons. Icons are resized to the deck requ icon: OFF_WHITE_FRAMED ``` +# Sounds + +Sounds files can be provided very much like icons. Valid sound file formats are `wav` and `mp3`. Other sound file format may be added in the future, provided they can be played in a browser. + # Documentation Documentation of the aircraft decks can be placed in the folder `deckconfig/docs` or in the folder `deckconfig/resources` in a textual form (including markdown), or as PDF. diff --git a/docs/Installation and Usage.md b/docs/Usage.md similarity index 58% rename from docs/Installation and Usage.md rename to docs/Usage.md index 68d1284b..3c7c2242 100644 --- a/docs/Installation and Usage.md +++ b/docs/Usage.md @@ -1,116 +1,10 @@ ![[installer.jpg|600]] -# Installation - -Cockpitdecks is a regular python application and will run with python 3.10, or newer. - -It is recommended to create a dedicated environment and run Cockpitdecks within that environment. - -## X-Plane *!* - -Cockpitdecks is a modern software that takes benefit from all available possibilities. While being developed, it is constantly updated to use the latest packages and features. - -Therefore, Cockpitdecks will work better with the latest production release of X-Plane. It may not work properly, or some feature may not be available when using older versions of X-Plane. We do not have the engineering resources to maintain working versions of Cockpitdecks for all versions of X-Plane. While most features should still work in X-Plane 11, they were never tested, and we will not provide any support to make it work on older release. - -Same occurs with aircrafts. Aircrafts are pieces of software that are regularly updated. It is a good practice to include the X-Plane and aircraft version information as comments in the `deckconfig` files, to precise which version of X-Plane or an aircraft is required to run properly. - -As a practical example, X-Plane recently opened access to internal data through a new channel: [A Web REST API access](https://developer.x-plane.com/article/x-plane-web-api/). This is offered in X-Plane release 12.1.1 or newer. Immediately, Cockpitdecks has taken benefit from this new, simplified mean to access internal values. - -It is good practice to maintain the software you use to the latest, production version. Cockpitdecks is no exception to this advise. - -In particular, the X-Plane Cockpitdecks Helper plugin uses and requires the latest version of [XPPython3](https://xppython3.readthedocs.io/en/latest/index.html) plugin to work. This plugin itself requires X-Plane 12 and recent version of X-Plane SDK. Cockpitdecks Helper plugin is strictly not required to run Cockpitdecks but some features will not work without it. - -### 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. -  -(See X-Plane UDP manual. Will provide information here later.) - -## Install Cockpitdecks Application - -### Install Cockpitdecks Software - -Create a new python environment and activate it. In that environment, issue the pip install command: - -```sh -pip install 'cockpitdecks[weather,streamdeck] @ git+https://github.com/devleaks/cockpitdecks.git' -``` - -Valid installable extras (between the `[` `]`, comma separated, no space) are: - -| Extra | Content | -| ------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `weather` | To load special iconic representation for weather. These icons sometimes fetch information outside of X-Plane. Recommended. | -| `streamdeck` | For Elgato Stream Deck decks | -| `loupedeck` | For Loupedeck LoupedeckLive, LoupedeckLive.s and Loupedeck CT devices | -| `xtouchmini` | For Berhinger X-Touch Mini device | -| `development` | For developer only, add testing packages and python types | - -### Install Cockpitdecks Helper Plugin - -> [!WARNING] Cockpitdecks X-Plane Helper Plugin -> You can do this step later, but some functions will not work or be available inside Cockpitdecks. - -X-Plane UDP has some shortcomings that prevent some operations with decks. - -To circumvent this, Cockpitdecks provides a small python plugin called the Cockpitdecks Helper plugin, that need to be installed into X-Plane. The Cockpitdecks Helper plugin will execute some instructions on behalf of the Cockpitdecks application. Cockpitdecks Helper plugin just need to be installed and will provide its services to Cockpitdecks. - -If not installed, some of the commands inside Cockpitdecks will work properly. - -#### 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. - -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. - -To collect string-typed datarefs, the **Cockpitdecks Helper** plugin needs to be installed in XPPython3 PythonPlugins folder. - -See [[String Datarefs]] for details about this. - -#### Cockpitdecks Helper Plugin Installation - -Cockpitdecks Helper Plugin is written in the python language. So it needs the [XPPython3](https://xppython3.readthedocs.io/) X-Plane plugin installed. XPPython3 plugin allow for execution of python code inside X-Plane. - -Cockpitdecks XPPython3 plugin is located in the - -```sh -< Cockpitdecks-installed-code > /cockpitdecks/resources/xppython3-plugins -``` - -folder in the source code. There is a single file. - -To install both services described above, copy the plugin file to: - -```shell -... /X-Plane 12/resources/plugins/PythonPlugins/PI_cockpitdecks.py -``` - -and ask XPPython3 plugin to reload the scripts. - -### Install Aircraft Specific `deckconfig` Folders - -Duane, a Cockpitdecks aficionado has realized several configurations for several aircrafts. - -You can [find them here](https://github.com/dlicudi/cockpitdecks-configs), download them and install them in your aircraft folder. - -Cockpitdecks `deckconfig` folder must be placed in the folder of the X-Plane aircraft to be found by Cockpitdecks or the Cockpitdecks Helper plugin. - -``` -/Aircraft/Extra Airicraft/Toliss A321/deckconfig -``` - -# Cockpitdecks Usage - -## Disconnect OEM Applications +# Disconnect OEM Applications First, you have to completely stop (quit completely) original manufacturer deck configuration applications. They take exclusive access to the device and that prevents Cockpitdecks from finding and using them. -## Adjust `config.yaml` +# Adjust `config.yaml` Cockpitdecks uses a single configuration 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 X-Plane folder path. @@ -130,13 +24,13 @@ The set of global parameters provided in the `config.yaml` file is called the Co Cockpitdecks provides two templates configuration files for local and remote use. -## Start Cockpitdecks +# Start Cockpitdecks Currently, Cockpitdecks only offers a command-line interface to be executed in a shell window. Installation of the above package in a python environment adds a single command `cockpitdecks-cli` that can be used to start Cockpitdecks and provide options. -### Command-Line Help +## Command-Line Help If always is a good idea to see what the client application offers: @@ -158,7 +52,7 @@ options:   -v, --verbose         show startup information ``` -### Test Cockpitdecks In Demonstration Mode +## Test Cockpitdecks In Demonstration Mode A second easy step is to start Cockpitdecks in demonstration mode. In this mode, it will offer a single demonstration web deck. See [[Examples]] for details about the demonstration. @@ -172,7 +66,7 @@ In this mode, Cockpitdecks will start a single web deck. Head for the index web ![[demo-deck.png]] -### Normal Operations +## Normal Operations There are two possible ways of working with Cockpitdecks: @@ -182,7 +76,7 @@ There are two possible ways of working with Cockpitdecks: > [!NOTE] > Cockpitdecks provides two templates global parameter/environment files to get you started. -### Cockpitdecks and X-Plane Run On Same Computer +## Cockpitdecks and X-Plane Run On Same Computer This is the simplest case. In this mode, everything is automatic. @@ -198,7 +92,7 @@ If no configuration is found, Cockpitdecks will listen and interpret X-Plane dat 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. -### Cockpidecks and X-Plane Run on Different Computer +## Cockpidecks and X-Plane Run on Different Computer In this case, it is not possible for Cockpitdecks to locate aircraft configuration files since they probably are on the remote computer. A set of configuration file will need to be supplied to Cockpitdecks on the command line to start with. (If no folder is supplied, Cockpitdecks will start in demonstration mode. See above.)