new structure, WIP

devleaks · Oct 11, 2024 · 9165494 · 9165494
1 parent 428bd95
commit 9165494
Show file tree

Hide file tree

Showing 19 changed files with 297 additions and 74 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,4 @@
 .obsidian/*
 .DS_Store
 docs/images/.DS_Store
+docs/images/.DS_Store
diff --git a/docs/Button/Button Activation.md b/docs/Button/Button Activation.md
@@ -11,7 +11,7 @@ This file list all activations that are currently available in Cockpitdecks. For
 - [[Button Activation#No Activation]]
 - [[Button Activation#Page]]
 - [[Button Activation#Push]]
-- [[Button Activation#Longpress]]
+- [[Button Activation#ShortOrLongpress]]
 - [[Button Activation#OnOff]]
 - [[Button Activation#UpDown]]
 - [[Button Activation#Encoder]]

diff --git a/docs/Button/Button Representations/Animations.md b/docs/Button/Button Representations/Animations.md
@@ -45,7 +45,7 @@ In this case, the animation controls and changes the value of the button, switch
 
 # Drawing Based Animation
 
-A Drawing animation is a parametrised drawing that uses a single parameter value (for exemple the button's value). When the value changes, the procedure optionally uses a tweening algorithm to progressively change the value from the old one to the new one.
+A Drawing animation is a parametrized drawing that uses a single parameter value (for exemple the button's value). When the value changes, the procedure optionally uses a tweening algorithm to progressively change the value from the old one to the new one.
 
 As a proof of this concept, the FollowTheGreens Representation displays a portion of taxiway centerline with "flashing" lead light when it is activated.
 

diff --git a/...n/Button Representations/Deck Specific.md → ...resentations/Deck Specific – Loupedeck.md b/...n/Button Representations/Deck Specific.md → ...resentations/Deck Specific – Loupedeck.md
@@ -8,34 +8,6 @@ They are either on or off, with a RGB color.
 colored-led: blue
 ```
 
-# EncoderLEDs
-
-`led: encoder-leds`
-
-(Specific to the X-Touch Mini Encoders.)
-
-MultiLeds are LED-based display that use more than one LED for reporting information.
-
-X-Touch Mini encoders, for example, are surrounded by 11 LED that can be lit individually.
-
-![[enc-status.png]]
-
-## Attributes
-
-`led-mode: fan` or `led-mode: 2`; name or number
-
-Valid modes are:
-
-0. Single
-1. Trim
-2. Fan
-3. Spread
-
-The value of the button determine how many leds will be displayed (0 to 11).
-
-> [!NOTE] X-Touch Mini MACKIE MODE
-> To send feedback instruction to the deck, two modes of interactions are available: Direct mode, and Mackie Mode. Cockpitdecks uses Mackie Mode which makes deck interaction easier and standard through the MIDI protocol. However, in Mackie Mode, only 11 or the 13 available encoder LEDs are accessible. It is not possible to access LED 0 and 13, only 1 to 12.
-
 # IconSide
 
 `icon-side: ICON_FILE_NAME`

diff --git a/docs/Button/Button Representations/Deck Specific – Stream Deck.md b/docs/Button/Button Representations/Deck Specific – Stream Deck.md
@@ -0,0 +1,68 @@
+# ColoredLed
+
+ColoredLed buttons are color capable led behind a transparent or mask button.
+
+They are either on or off, with a RGB color.
+
+```
+colored-led: blue
+```
+
+The Elgato Stream Deck Neo has two small colored led on each side of the LCD display.
+
+# Larger Displays
+
+Some decks exhibit displays that are larger than a key with and iconic representation. Those displays often have touch and swipe capabilities. This led to design activations and representations specific to these larger displays to be used with your favourite flight simulation software.
+
+> Please note, for example, that the LoupedeckLive deck has a unique central display screen accepting touches and swipes. A plastic grid cover gives the illusion that there are two vertical side screens and 12 « keys » in the middle, but underlying is a unique 480 × 360 pixel screen. Each key is a 90 × 90 pixel portion of that screen.
+
+## Usage
+
+Larger screens can be used in two different ways:
+
+- As a whole, unique, larger display surface,
+- As a set of adjacent buttons covering the entire surface.
+
+In the later case, the specificity of the display is not apparent, and resulting buttons are treated as regular keys with iconic image display (with different sizes sometimes.) This is called a [[Multi-Buttons and Mosaic|Mosaic]].
+
+When considered as a single larger display, it is difficult to remain generic since each display will have special size, location, and behavior. Cockpitdecks buttons assigned to those specific display are therefore also very specific.
+
+## Activations
+
+Having no activation at all to use those display solely for displaying purposes is always an option. However simple activations can make the passive display a lot more enjoyable.
+
+For exemple, if the display is capable, touching or swiping the display can be used to change its content. On startup, display heading, swipe left, display speed, swipe right display heading, etc.
+
+## Touch
+
+Touch is similar to button press activation and can be used as such.
+
+## Swipe
+
+Swipe returns movement start and end position and timing. These values can be interpreted to model a limited set of movements like swipe left, right or up, down. Raw values can also be used as an increasing or decreasing sliding cursor.
+
+## Representations
+
+Given the sizes of each display, representations fitting those displays will always remain very specific.
+
+### Larger Horizontal Displays
+
+#### Airbus Flight Control Unit
+
+The highly specific Airbus FCU representation reproduces the central display with all possible modes.
+
+#### Airbus Flight Mode Annunciators
+
+The Airbus FMA displays the five annunciators on top of the Primary Flight Display (PFD).
+
+There are two modes of display. The first one make use of a larger, horizontal display and shows all five annunciators next to each other. The second one use five keys with iconic display and show one annunciator on one key. In both cases, data necessary for display is fetched only once, the first annunciator being the master one with all data, other annunciators are slave ones and fetch their data from the master annunciator.
+
+Airbus FMA display is a pure display with no activation associated with it.
+
+### Larger Vertical Displays
+
+On LoupedeckLive decks, vertical displays exploit their proximity to the lateral encoder dials to present direct encoder feedback. For example, next to the QNH adjustment encoder, the current atmospheric pressure is displayed. Pushing the encode switches between Standard pressure and local ambiant pressure.
+
+### Icons
+
+Image or drawn icons (especially text messages) are also an alternative way to decorate those displays. One can imagine displaying ATC instructions on a tape display, with swipe actions to acknowledge messages.
diff --git a/docs/Button/Button Representations/Deck Specific – X-Touch Mini.md b/docs/Button/Button Representations/Deck Specific – X-Touch Mini.md
@@ -0,0 +1,35 @@
+# EncoderLEDs
+
+`led: encoder-leds`
+
+(Specific to the X-Touch Mini Encoders.)
+
+MultiLeds are LED-based display that use more than one LED for reporting information.
+
+X-Touch Mini encoders, for example, are surrounded by 11 LED that can be lit individually.
+
+![[enc-status.png]]
+
+## Attributes
+
+`led-mode: fan` or `led-mode: 2`; name or number
+
+Valid modes are:
+
+0. Single
+1. Trim
+2. Fan
+3. Spread
+
+The value of the button determine how many leds will be displayed (0 to 11).
+
+> [!NOTE] X-Touch Mini MACKIE MODE
+> To send feedback instruction to the deck, two modes of interactions are available: Direct mode, and Mackie Mode. Cockpitdecks uses Mackie Mode which makes deck interaction easier and standard through the MIDI protocol. However, in Mackie Mode, only 11 of the 13 available encoder LEDs are accessible. It is not possible to access LED 0 and 13, only 1 to 12.
+
+## Value Mapping
+
+If nothing is specified, raw button value is used.
+
+If `value_min` and `value_max` are specified in the encoder attribute, the Encoder representation performs a linear mapping between (`value_min`, `value_max`) and the range of valid values (0, 10).
+
+A Warning is issued if the value is out of the range 0-11.
diff --git a/docs/Button/Button Representations/Charts.md → ...Representations/Drawn Buttons – Charts.md b/docs/Button/Button Representations/Charts.md → ...Representations/Drawn Buttons – Charts.md
diff --git a/...resentations/Drawn Buttons (continued).md → ...tions/Drawn Buttons – Gauges and Tapes.md b/...resentations/Drawn Buttons (continued).md → ...tions/Drawn Buttons – Gauges and Tapes.md
@@ -41,4 +41,4 @@ A special gauge is the heading gauge (called `rose`) which show the heading on a
 
 # Charts
 
-Cockpitdecks provides a limited set of time-based [[Charts|display charts]], also often called [sparklines](https://en.wikipedia.org/wiki/Sparkline).
+Cockpitdecks provides a limited set of time-based [[Drawn Buttons – Charts|display charts]], also often called [sparklines](https://en.wikipedia.org/wiki/Sparkline).
diff --git a/docs/Cockpit.md b/docs/Cockpit.md
@@ -53,12 +53,12 @@ The  `deckconfig` folder contains the following files and sub-folders:
 
 # `config.yaml` File
 
-The file named `config.yaml` in the `deckconfig` folder contains declarations for each [[cockpitdecks-docs/docs/Deck|deck]] that will be used and global, aircraft-level attributes.
+The file named `config.yaml` in the `deckconfig` folder contains declarations for each [[Deck|deck]] that will be used and global, aircraft-level attributes.
 
 ```yaml
 # Definition of decks for Toliss A321
 #
-aicraft: Toliss 
+aircraft: Toliss 
 decks:
   - name: XPLive
     type: loupedeck
@@ -84,7 +84,7 @@ The parameters apply to all decks for the given aircraft. Each individual deck w
 | `cockpit-texture`        | Name of a image file (JPEG or PNG) that will be used as the (default) background of icons.<br><br>The `cockpit-texture` file will be searched at different places depending on where it is specified.<br><br>The `cockpit-texture` file can be specified at the Cockpit, Deck, Page, or Button level.<br><br>Cockpit-level default textures will be seached in the following folders (in that order):<br><br>- `resources`<br>- `resources/icons`<br><br>If the AIRCRAFT is specified, Cockpit-level textures and all other levels textures will be searched in the following folders:<br><br>- `AIRCRAFT/resource`<br>- `AIRCRAFT/icons`<br><br>If no texture is found, a uniform `cockpit-color` icon is used. |
 | `default-wallpaper-logo` | Name of image file, located in the `resource` folder, to be loaded when the deck is not used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `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 [[cockpitdecks-docs/docs/Deck]] structure, one per deck.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **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.
 

diff --git a/docs/Creating/Adding a Page of Buttons to a Deck.md b/docs/Creating/Adding a Page of Buttons to a Deck.md
@@ -0,0 +1,76 @@
+This page is an attempt at providing all necessary step to create a new page of buttons to display on a deck.
+
+We assume you installed Cockpitdecks properly, together with the Cockpitdecks Helper Plugin which is necessary to work in fully automatic mode.
+
+# Deck Preparation
+
+First, make sure the deck model you own is a deck already available through Cockpitdecks. The following deck brands and models have been tested and used:
+
+- Elgato Strem Deck: Streamdeck MK.2, Streamdeck XL, Streamdeck Mini, Streamdeck+, Streamdeck Neo
+- Loupedeck: LoupedeckLive, LoupedeckLive.s
+- Behringer: X-Touch Mini (I recently noticed that there are several version of the same device, but they should all work since the Makie mode is used.)
+
+## Prepare the Folder
+
+In normal, simple, automatic mode, Cockpitdecks expects configuration to be found in the folder of the aircraft currently being used. (This may be adjusted by advanced configuration parameters if you do not want to store Cockpitdecks configuration files in the that folder.)
+
+In the aircraft folder, create a folder named `deckconfig`.
+
+## Add the main `config.yaml`File
+
+Inside the above folder, create the main configuration file with this content. Adjust the content to your deck.
+
+```
+aircraft: Cessna 172 
+decks:
+  - name: Aviator Loupdeck
+    type: loupedeck
+    layout: cockpit
+    brightness: 70
+```
+
+## Create a layout Folder
+
+In the conifiguration file, you mention the name of the layout you are going to use for that deck: `cockpit`. Inside the deckconfig folder, create a sub-folder and name it `cockpit`.
+
+## Add a Page
+
+Inside that `cockpit` folder, create a file `index.yaml`. Insert the following content in the file:
+
+```
+buttons:
+  - index: 0
+    label: Map
+    type: push
+    icon: map
+    command: sim/map/show_current
+```
+
+## First Run
+
+Start X-Plane, load the aircraft where you created your Cockpitdecks configuration folder.
+
+Disconnect all software that access your deck.
+
+### Create an Environment File
+
+If every runs on the same computer, you only need to supply X-Plane home directory. You can supply the folder either through a operating system environment variable `SIMULATOR_HOME`, or through the Cockpitdecks environment file. A `myenviron.yaml` file with the following content is sufficient:
+
+```
+SIMULATOR_NAME: X-Plane
+SIMULATOR_HOME: /Applications/X-Plane 12
+```
+
+### Start Cockpitdecks
+
+```
+$ cockpitdecks-cli --env myenviron.yaml
+```
+
+Cockpitdecks will start immediately in demonstration mode, and connect to the simulator. Once it is connected to the simulator, it will try to collect the information about the aircraft that is currently loaded. This may take a few seconds. Once Cockpitdecks has the information about the aircraft currently being used, it will search for the deckconfig folder in the folder of the aircraft, and if found, will load the configuration it finds there.
+
+If everything worked properly, you should now see the first, upper left button of your deck displaying the Map text. With no map icon.
+
+## Adding Custom Icons
+
+# Add buttons
diff --git a/docs/Creating/Adding a Web Deck.md b/docs/Creating/Adding a Web Deck.md
@@ -0,0 +1,3 @@
+# Adding an Existing Web Deck
+
+# Creating a New Web Deck
diff --git a/docs/Extending/Button Activations for Developers.md b/docs/Extending/Button Activations for Developers.md
@@ -40,16 +40,16 @@ The value of the `what` attribute determine what is displayed when activated.
 
 ### what Attribute Values
 
-| Value               | Description                                                                                                                                                                        |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `threads`           | list Cockpitdecks and deck threads that are currently running.                                                                                                                     |
-| `datarefs`          | list datarefs and values (the page containing the buttons need to be loaded first before it can display values).                                                                   |
-| `datarefs-listener` | List all datarefs and which buttons (listeners) are using the dataref.                                                                                                             |
-| `status`            | list internal variables and statuses of each button.                                                                                                                               |
-| `valid`             | check button validity and report invalid status.                                                                                                                                   |
-| `desc`              | print a description of what each button does in plain English, both for activation and representation.                                                                             |
-| `image`             | produces an image of each deck, images are saved in the Cockpitdecks home directory and named after the deck.                                                                      |
-| `longpress`         | list [[Button Activation#Longpress\|Longpress]] command that should have a couple of additional commands [[X-Plane Interaction#Activations\|added to X-Plane through the plugin]]. |
+| Value               | Description                                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `threads`           | list Cockpitdecks and deck threads that are currently running.                                                                                                                 |
+| `datarefs`          | list datarefs and values (the page containing the buttons need to be loaded first before it can display values).                                                               |
+| `datarefs-listener` | List all datarefs and which buttons (listeners) are using the dataref.                                                                                                         |
+| `status`            | list internal variables and statuses of each button.                                                                                                                           |
+| `valid`             | check button validity and report invalid status.                                                                                                                               |
+| `desc`              | print a description of what each button does in plain English, both for activation and representation.                                                                         |
+| `image`             | produces an image of each deck, images are saved in the Cockpitdecks home directory and named after the deck.                                                                  |
+| `longpress`         | list [[Button Activation#ShortOrLongpress]] command that should have a couple of additional commands [[X-Plane Interaction#Activations\|added to X-Plane through the plugin]]. |
 
 ```Yaml
 index: 4
Original file line number	Diff line number	Diff line change
Expand Up		@@ -41,4 +41,4 @@ A special gauge is the heading gauge (called `rose`) which show the heading on a

		# Charts

		Cockpitdecks provides a limited set of time-based [[Charts\|display charts]], also often called [sparklines](https://en.wikipedia.org/wiki/Sparkline).
		Cockpitdecks provides a limited set of time-based [[Drawn Buttons – Charts\|display charts]], also often called [sparklines](https://en.wikipedia.org/wiki/Sparkline).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Adding an Existing Web Deck

		# Creating a New Web Deck