Skip to content

Commit

Permalink
split install/use
Browse files Browse the repository at this point in the history
  • Loading branch information
@devleaks
devleaks committed Oct 1, 2024
1 parent 69cd888 commit 478529e
Show file tree
Hide file tree
Showing 4 changed files with 119 additions and 116 deletions.
4 changes: 2 additions & 2 deletions docs/Extending/Internals/Deck Internals.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
105 changes: 105 additions & 0 deletions docs/Installation.md
View file
Original file line number Diff line number Diff line change
@@ -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.

```
<X-Plane 12 Folder>/Aircraft/Extra Airicraft/Toliss A321/deckconfig
```

Now you are ready to [[Usage|start Cockpitdecks]].
4 changes: 4 additions & 0 deletions docs/Resources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
122 changes: 8 additions & 114 deletions docs/Installation and Usage.md → docs/Usage.md
View file
Original file line number Diff line number Diff line change
@@ -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.

```
<X-Plane 12 Folder>/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.

Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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.)

Expand Down

0 comments on commit 478529e

Please sign in to comment.