Skip to content

Commit

Permalink
rewrite introduction
Browse files Browse the repository at this point in the history
  • Loading branch information
@devleaks
devleaks committed Nov 4, 2024
1 parent 9d538ab commit 6f9c6b7
Show file tree
Hide file tree
Showing 6 changed files with 76 additions and 42 deletions.
15 changes: 12 additions & 3 deletions docs/Button.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
40 changes: 27 additions & 13 deletions docs/Cockpit.md
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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 |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -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.<br><br>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

Expand All @@ -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. |
Expand All @@ -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.
2 changes: 2 additions & 0 deletions docs/Extending/Web Decks.md
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
12 changes: 6 additions & 6 deletions docs/Installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.)

Expand Down Expand Up @@ -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.

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

Expand Down
Loading

0 comments on commit 6f9c6b7

Please sign in to comment.