document about page info and settings (#1892)

* document about page info and settings Signed-off-by: Stefan Höhn <[email protected]> * fix typos in about-page doc Signed-off-by: Stefan Höhn <[email protected]> * fix md error Signed-off-by: Stefan Höhn <[email protected]> * copy images in processing, layout changes Signed-off-by: Stefan Höhn <[email protected]> * fix more md issues Signed-off-by: Stefan Höhn <[email protected]> * document Configuration section of Settings Signed-off-by: Stefan Höhn <[email protected]> * Update settings/aboutpage.md Co-authored-by: Jerome Luckenbach <[email protected]> * Update settings/aboutpage.md Signed-off-by: Jerome Luckenbach <[email protected]> Signed-off-by: Stefan Höhn <[email protected]> Signed-off-by: Jerome Luckenbach <[email protected]> Co-authored-by: Jerome Luckenbach <[email protected]>
openhab · Oct 2, 2022 · 4cf51ae · 4cf51ae
1 parent 14dbc2f
commit 4cf51ae
Show file tree

Hide file tree

Showing 19 changed files with 147 additions and 32 deletions.
diff --git a/.vuepress/process_main_docs.rb b/.vuepress/process_main_docs.rb
@@ -89,7 +89,8 @@ def process_main_docs(docs_source_dir)
         puts " -> #{file}"
         process_file("#{docs_source_dir}/settings", file, "docs/settings", "#{$docs_repo_root}/settings/#{file}")
     }
-    # TODO => Add images logic if necessary
+    puts " -> images"
+    FileUtils.cp_r("#{docs_source_dir}/settings/images", "docs/settings/images")
 
     puts ">>> Migrating the Migration Tutorial section"
 

diff --git a/settings/aboutpage.md b/settings/aboutpage.md
@@ -5,7 +5,7 @@ title:  Help & About Page
 
 # Help & About Page
 
-The about page allows to configure some client related configuration
+The about page shows general information of your openHAB configuration and  allows to configure some client related configuration.
 
 {::options toc_levels="2..4"/}
 
@@ -14,43 +14,121 @@ The about page allows to configure some client related configuration
 
 ## Top Section
 
-- Version
-- Links to the openHAB Website, the openHAB Documention and the Community Forum
+![img.png](images/about-top-section.png)
+
+- Version: shows the currently installed version of openHAB
+- Links to the official openHAB Website, the openHAB Documentation and the Community Forum
 
 ## Technical Information
 
-- Configuration folder
-- User data folder
-- Logs folder
-- Operating System
-- Java Runtime
-  - View Details
+This section is collapsed by default and can be opened by clicking on it which then reveals the
+
+- Configuration folder on the server
+- User data folder on the server
+- Logs folder on the server
+- Operating System openHAB is running on
+- Java Runtime openHAB is running on
+- number of processors and memory
+
+Clicking on View Details opens up a popup window that contains very detailed information like
+
+- Runtime information
+- Locale (language)
+- System information including memory information
+- A list of all installed bindings
+- Client information including device information, client settings (see also the below section), screen information, theme, user agent information.
+
+The content can be easily copied with the copy button on the top to provide it as additional information when asking questions in the community.
 
 ## Appearance (for this device only)
 
-- Theme
-![Theme](theme-selection.png)
+This section allows to have different appearance settings _per_ device.
+
+- **Theme**: Selects the theme for that device
   - Auto: tries to detect the client type
   - Android
   - iOS
   - Destktop
-- Dark mode setting
-![Dark-Mode](dark-mode.png)
-  - Auto: **TODO**
+
+![theme-selection.png](images/theme-selection.png)
+
+- **Dark mode** setting
+  - Auto: uses the default mode
   - Light-Mode
   - Dark-Mode
-- Navigation bars style
-![Navigation bars style](navbar-style.png)
+
+![dark-mode.png](images/dark-mode.png)
+
+- **Navigation bars style**: inverts the colors in the navigation bar
+
+![navbar-style.png](images/navbar-style.png)
 
 # Miscellaneous settings
 
-- Simple navigation bar on home page: **TODO** What is the navigation bar
-- Standard home page background color: **TODO**
-- Disable card expansion animations: Disables the animations when expanding a widget card
-- Disable page transition animations: Disables the transitions when switching from one page to the other
-- Enable Web Audio sink support
-  - **TODO** : see [https://github.com/openhab/openhab-webui/pull/1422](https://github.com/openhab/openhab-webui/pull/1422)
+- **Simple navigation bar on home page**: When switching it on, it means the navigation bar will look the same even whether you're at the top of the page or not - you won't have the alternate look with the date.
+The first image depicts the normal setting (off), the second image shows it switched off
+
+![simple-nav-off.png](images/simple-nav-off.png) ![simple-nav-on.png](images/simple-nav-on.png)
+
+- **Standard home page background color**: This only relates to the light color scheme.
+The background color will be the same as the regular pages you can show from e.g. the sidebar, which is a kind of gray instead of white.
+The first image depicts the normal white setting (off), the second image shows it switched off with the gray setting.
+
+![bg-white-setting.png](images/bg-white-setting.png) ![bg-gray-setting.png](images/bg-gray-setting.png)
+
+- **Disable card expansion animations**: Disables the animations when expanding a widget card.
+- **Disable page transition animations**: Disables the transitions when switching from one page to the other.
+
+# Enable Web Audio sink support
+
+- This setting is also part of the miscellaneous settings.
+- The intent of that option is to allow sending audio to that device, e.g. if that device is a tablet that is hanging on the wall in a room and a specific audio should be sent to that device for notification purposes.
+- To activate audio output of that particular device, switch on this option.
+In case you want to activate audio on multiple devices, each device needs to be activated by opening the about page on the device.
+Technically, this information (and all the other miscellaneous settings) are stored in the local storage of the browser.
+- For me information [see here](https://github.com/openhab/openhab-webui/pull/1422)
+
+To test if it works play some static content that comes with openHAB in the /sounds dir using a console command.
+Use [openHABs console](administration/console.html#using-the-console) to enter the following command:
+
+```text
+openhab> audio play webaudio barking.mp3
+```
+
+If you have a dog that gets triggered by barking you may opt for playing doorbell.mp3 instead.
+If you play doorbell.mp3 your dog will then probably play its own barking audio sound. 😉
+Note that most browsers block web pages from playing audio/video automatically nowadays (though some browsers have a setting to activate automatic play)
+
+Here are some useful actions available to rules in which you can specify webaudio as sink, see:
+
+- [playSound](/docs/configuration/multimedia.html#actions-2)
+
+```text
+playSound("webaudio", "barking.mp3")
+```
+
+- [say](/docs/configuration/multimedia.html#actions-3)
+
+```text
+say("Hello world!", "voicerss:enUS", "webaudio")
+```
+
+You can also configure webaudio as sink when creating rules in the UI:
+
+![play-rule.png](images/play-rule.png)
+
+or using it in a blockly rule:
+
+![webaudio-blockly.png](images/webaudio-blockly.png)
+
+It is important to understand that you cannot address one particular device.
+When you play a sound on webaudio, it will be played on each device where webaudio is activated.
+
+If you really like webaudio, you can also make it the default sink in the "Audio" settings - see [Settings->Audio](/docs/settings/services-system.html#Audio).
+Then you can omit the webaudio sink ID from commands/actions.
+
+![settings-audio.png](images/settings-audio.png)
 
 # Reload
 
-Reload the web page to see the selected changes.
+Reload the web page to reflect the selected changes.
diff --git a/settings/configuration.md b/settings/configuration.md
@@ -5,20 +5,56 @@ title:  Configuration
 
 # Settings - Configuration
 
-This is the section for the configuration of things, items and the openHAP pages resided
+This section allows the configuration of things, items and user interface pages
 
 - TOC
   [[toc]]
 
+Next to the entity the count of that entity is shown, though the Things count is not the number of all configured Things but the count of the Things waiting in the [Inbox](docs/tutorial/things_simple.html#accept-the-light-bulb-things).
+
+![config-overview.png](images/config-overview.png)
+
 ## Things
 
-Manage the physical layer
+_Things_ manage the physical layer of the openHAB System.
+There is a [Things concepts page](/docs/concepts/things.html) that explains the idea of Things in detail.
+
+The general explanation on how to **configure things** via things-files is described in the [Things configuration page](http://localhost:8000/docs/configuration/things.html)
+
+Adding Things via the user interface as part of the _settings section_ is described comprehensively in the tutorial section
+
+- [Addings Things - Simple](docs/tutorial/things_simple.html)
+- [Adding Things - Intermediate](docs/tutorial/things_intermediate.html): Things that are dealing with a binding where the bridge-Thing cannot be automatically discovered.
+- [Adding Things - Advanced](things_advanced.html): Things that do not support automatic discovery
+
+## Semantic Model and Items
+
+_Items_ manage the functional layer of openHAB.
+Items, which are linked to a Thing, represent functionality that is used by the application (mainly user interfaces or automation logic).
+Items have a state and are used through events.
+
+There is an [Items concepts page](docs/concepts/items.html) that explains the idea of Items in detail.
+
+The general explanation on how to **configure items** via things-files is described in the [Items configuration page](http://localhost:8000/docs/configuration/items.html)
+
+An integral part on how to model items is the [Semantic Model](http://localhost:8000/docs/tutorial/model.html) of your home which structures Items in a hierarchical, tree-like model.
+That documentation also explains [how to build the Model](docs/tutorial/model.html#building-the-locations-model) via the openHAB user interface.
+
+## User Interface Pages
+
+This configuration section allows to design displays for user control & monitoring.
+openHAB 3 has introduced a new unified user interface called MainUI. Almost everything that can be configured in openHAB can be configured through MainUI.
 
-## Items and the semantic Model
+Though openHAB automatically creates an [overview page](docs/tutorial/auto_overview.html#overview-page) based on the semantic model, it also allows to design and create custom user interface pages with sophisticated [standard widgets](docs/tutorial/item_widgets.html) and [custom widgets](docs/tutorial/custom_widgets.html).
+Therefore, it is highly recommended reading the [User Interface Design Overview](http://localhost:8000/docs/ui/) first.
 
-- Model: The semantic model of your home
-- Items: Manage the functional layer
+The [pages tutorial section](docs/tutorial/pages_intro.html) explains how to create and design user interface pages within openHAB.
 
-## User Interfaces Pages
+Within this section the following page types can be created:
 
-Design displays for user control & monitoring
+- [Layout](docs/ui/layout-pages.html): Layout Pages are used in the main web user interface to display widgets in an organized manner.
+- [Tabbed Pages](/docs/ui/tabbed-pages.html): Tabbed Pages are composite Pages which are able to display other Pages in tabs.
+- [Charts](docs/ui/chart-pages.html): Chart Pages can display historical values in a full-screenchart component.
+- [Floor Plans](docs/ui/floorplan-pages.html): Floorplan Pages can display markers or other elements over a custom image.
+- [Map Views](docs/ui/map-pages.html): Map Pages can display either fixed markers or markers representating items of type Location, on a map.
+- [Sitemap](docs/ui/sitemaps.html): Sitemaps have existed since the first versions of openHAB and were used as an easy way display items. Keep in mind that the main UI is not currently able to display them, though the mobile apps still are.
diff --git a/settings/dark-mode.png b/settings/dark-mode.png
diff --git a/settings/images/about-top-section.png b/settings/images/about-top-section.png
diff --git a/settings/images/bg-gray-setting.png b/settings/images/bg-gray-setting.png
diff --git a/settings/images/bg-white-setting.png b/settings/images/bg-white-setting.png
diff --git a/settings/images/config-overview.png b/settings/images/config-overview.png
diff --git a/settings/images/dark-mode.png b/settings/images/dark-mode.png
diff --git a/settings/images/navbar-style.png b/settings/images/navbar-style.png
diff --git a/settings/images/play-rule.png b/settings/images/play-rule.png
diff --git a/settings/images/settings-audio.png b/settings/images/settings-audio.png
diff --git a/settings/images/simple-nav-off.png b/settings/images/simple-nav-off.png
diff --git a/settings/images/simple-nav-on.png b/settings/images/simple-nav-on.png
diff --git a/settings/images/theme-selection.png b/settings/images/theme-selection.png
diff --git a/settings/images/webaudio-blockly.png b/settings/images/webaudio-blockly.png
diff --git a/settings/navbar-style.png b/settings/navbar-style.png
diff --git a/settings/theme-selection.png b/settings/theme-selection.png
diff --git a/tutorials/getting_started/things_simple.md b/tutorials/getting_started/things_simple.md
@@ -95,7 +95,7 @@ You will notice a new red button on that screen.
 This means that there are newly discovered devices that you can add.
 Since the Hue bridge is now working, the binding has detected all the Hue devices (bulbs, switches and so on) attached to it.
 
-The Inbox shows a consolidated view of all the discovery results.
+The Inbox shows a consolidated view of all the discovery results which can sorted alphabetically or grouped by binding type (see tabs).
 Alternatively, you can also click on the "+" button to get a per-binding view and the ability to perform a new scan.
 
 Click Inbox.