Merge branch 'main' of https://github.com/andrewfg/openhab-docs

addons/uis/apps/ios.md

@@ -5,44 +5,172 @@ title: iOS App
 
 # iOS App
 
-<!-- https://developer.apple.com/app-store/marketing/guidelines/de/#downloadOnAppstore -->
-
 The openHAB iOS application is a native client for openHAB, compatible with iPhone and iPad.
-It uses the REST API of openHAB to render sitemaps of your openHAB installation for a natural iOS feeling.
 
-<a href="https://itunes.apple.com/us/app/openhab/id492054521">
-  <img alt="Download on the App Store" src="images/download-on-the-app-store.png" width="240px">
-</a>
+## openHAB (Primary)
+
+This is the primary openHAB app which contains the latest features and is updated regularly. This includes Apple Watch support, enhanced notifications, widgets and more.
+Requires at least iOS 16 and openHAB 2.x and later.
+
+(Official App Store Link Coming Soon)
+
+<a href="https://testflight.apple.com/join/0uFYONeF"><img src="https://developer.apple.com/assets/elements/icons/testflight/testflight-128x128_2x.png" width="75" alt="Download on TestFlight"></a>
+Beta releases are available on [TestFlight](https://testflight.apple.com/join/0uFYONeF).
+
+## openHAB V1 (Legacy)
+
+This is the legacy app for users on iOS 15 or earlier as well as openHAB system 1.x and later (tested to at least openHAB 4).
+This app only receives security updates and minor fixes and is not intended for most users.
+
+<a href="https://itunes.apple.com/us/app/openhab/id492054521?ls=1&mt=8"><img src="images/download-on-the-app-store.png" alt="Download on the App Store" width="150px"></a>
+
+Beta releases are available on [TestFlight](https://testflight.apple.com/join/563WBakc).
 
 ## Features
 
-- View and control openHAB sitemaps
-- Connect to local openHAB instances on the local network
-- Connect to your openHAB instance remotely, either using a direct connection or via myopenHAB
-- Receive push notifications on your iOS devices via myopenHAB
+- Control your openHAB server directly and through a [openHAB Cloud instance](https://github.com/openhab/openhab-cloud)
+- [Enhanced push notification](#push-notifications) from openHAB Cloud and the openHAB cloud binding
+- [Apple Watch](#apple-watch-configuration) companion app
+- [Widgets](#widgets) (coming soon!)
 - Natively supports both iPhone and iPad
 
-<div class="row">
-  <div class="col s12 m4"><img src="images/ios01.png" alt="Demo Main Menu"></div>
-  <div class="col s12 m4"><img src="images/ios02.png" alt="Demo Widget Overview"></div>
-  <div class="col s12 m4"><img src="images/ios03.png" alt="Settings"></div>
-</div>
+<p float="left">
+  <img src="images/mainui.png" alt="Main UI" width="200">
+  <img src="images/sitemap.png" alt="Sitemap" width="200">
+</p>
+
+## App Configuration
+
+<p float="left">
+<img alt="Logo" src="images/settings1.jpeg" width="200">
+<img alt="Logo" src="images/settings2.jpeg" width="200">
+</p>
+
+### Connection Settings
+
+The app will try and connect using the Local URL as the primary connection, and if that fails or is not reachable, falls back to the Remote URL.  
+
+### Demo Mode
+
+This sets up the app to use the openHAB demo server and can be used to experience the app without needing to install openHAB.
+
+#### Local URL
+
+This is the primary connection to your openHAB instance, a fully qualified URL with a IP or host is required.
+
+Example:
+`https://openhab.local:8443`
+
+#### Remote URL
+
+This is the secondary connection to your openHAB instance, a fully qualified URL with a IP or host is required.
+If using the openHAB cloud service, leave this as the default setting of `https://myopenhab.org`.
+When set to the public cloud, the app will also register for push notifications (as long as credentials are correct)
+
+Example:
+`https://myopenhab.org`
+
+### Username / Password
+
+This will be sent if the local or remote server challenges for authentication, or if "Always Send Credentials" is checked on.
+If using the openHAB cloud, these should be set to those login credentials.
+
+### Application Settings
+
+### Certificates
+
+Allows the installation of p12 formatted certificates for use in client side authentication setups.
+
+To install a client certificate, rename the certificate with the extension `.ohp12`, then send it to your iOS device (airdrop, icloud, dropbox, etc..), then open/save and select `openHAB` from the "Open In" menu (you may need to select "More..." to see all apps).
+
+To delete a certificate, swipe left on the certificate name in the certificate menu.
+
+If using openssl v3 to generate certificates, make sure to add `-legacy -certpbe pbeWithSHA1And40BitRC2-CBC` to the pk12 export command.
+See [Apple OpenSSL 3.0.x Issues](https://github.com/openssl/openssl/issues/19871) for more information on V3 compatibility with Apple products.  
+
+### Idle Timeout
+
+Useful for wall or fixed installations, will disable the Idle screen timeout.
+
+### Crash Reporting
+
+Sends crash reports to Google / Firebase.
+
+### Main UI Settings
+
+#### WebRTC
+
+Allows audio and video communications in the Main UI for views and widgets that require it.
+
+#### Default Path
+
+Allows the user to enter a path to act as the starting point when the Main UI is loaded.
+Clicking the "+" button will prompt to enter the current path the of Main UI view.
+
+#### Clear Cache
+
+Clears the Main UI web cache.
+
+### Sitemap Settings
+
+#### Realtime Sliders
+
+Allows sitemap sliders to send changes as the control is sliding in realtime.
+
+### Image Cache
+
+Clears the sitemap cached images.
+
+### Icon Type
+
+Select which type of icon the sitemap view will attempt to load for icons.
+
+### Sitemap Sorting
+
+Sort order when presenting multiple sitemaps for selection.
+
+## Apple Watch Configuration
+
+The Apple watch requires a sitemap with the name `watch.sitemap`.
+Note that some advanced sitemap features may not be supported on the Apple watch and its recommended to keep this sitemap simple and appropriate for interaction on a small display.
+
+When using the Watch app, slide left to bring up the configuration view and select "sync" to ensure the local, remote and username/password configurations are synced to the watch.
+
+## Main UI and Sitemap Usage
+
+<img alt="Side Menu" src="images/sidemenu.jpeg" width="200">
+
+Clicking "Home" will navigate to the Main UI from the user's openHAB system.  Clicking this when the Main UI is already visible will force a reload the Main UI.
+
+Tiles are the alternative UIs installed on a user's system and will be opened in an embedded browser.
+
+Sitemaps show the available sitemaps on the users system.  Selecting a sitemap will present the native sitemap renderer view.
+
+Notifications is a list of push notification retrieved from the openHAB cloud (if configured).
+
+Settings opens the application settings view.
+
+The app will persist the last primary view opened (Main UI or Sitemaps) when the app is opened or restarted.
+
+## Push Notifications
+
+The [openHAB Cloud Connector](https://next.openhab.org/addons/integrations/openhabcloud/)  allows users to send push notifications mobile devices registered with an [openHAB Cloud instance](https://github.com/openhab/openhab-cloud) such as [myopenHAB.org](https://www.myopenhab.org).
 
-## Installation and Setup
+<p float="left">
+<img alt="Notifications" src="images/notifications.png" width="500">
+</p>
 
-The latest release version of the app is always available through the Apple App Store.
+Push Notifications on iOS support:
 
-The app will start in Demo mode by default.
-A demo home automation setup is shown.
-This allows you to explore the possibilities of a typical openHAB installation.
+- Title and message text
+- Image and video attachments
+- Up to 3 action buttons (long press notification)
+- Collapsible / updated notifications
+- Removing notifications
 
-To view and control your own devices, navigate to the Settings page, then disable the "Demo mode" checkbox.
-In the "Local URL" field enter the base URL to your openHAB webinterface, either using its IP address (e.g. `http://192.168.1.125:8080`) or hostname (e.g. `http://openhabianpi:8080`).
+## Widgets
 
-You can also connect to openHAB remotely, using either a direct connection or an openHAB Cloud instance like myopenHAB.
-Please see the [article on secure remote access](https://docs.openhab.org/installation/security.html) for more details.
-Simply enter your "Remote URL" in the respective Settings field.
-The openHAB app will henceforth first try connecting to the local URL, then fall back to the remote URL.
+Coming soon !
 
 ## Help and Resources
 

addons/uis/apps/windows.md

@@ -13,4 +13,8 @@ The latest release version of the app is always available through the Windows St
 
 Please refer to the [openhab.windows project](https://github.com/openhab/openhab.windows) on GitHub for more technical details.
 
-{% include contribution-wanted.html %}
+::: tip Contribution Wanted
+Please help us improve the documentation!
+If you'd like to leave corrections, additions or comments for this article or any other part of this website, please drop a word at:
+[Documentation Issue Tracker](https://github.com/openhab/openhab-docs/issues) or open a new PR.
+:::

administration/index.md

@@ -10,4 +10,8 @@ Karaf provides features such as a console CLI, remote access, hot deployment of
 The Karaf Console is a powerful tool for interacting with and controlling your openHAB installation.
 You will learn more about advanced administration of your openHAB installation, using the Karaf Console and other tools, in this section.
 
-{% include contribution-wanted.html %}
+::: tip Contribution Wanted
+Please help us improve the documentation!
+If you'd like to leave corrections, additions or comments for this article or any other part of this website, please drop a word at:
+[Documentation Issue Tracker](https://github.com/openhab/openhab-docs/issues) or open a new PR.
+:::

appendix/help.md

@@ -17,4 +17,8 @@ Check there before posting your own questions and feel free to add questions and
 
 - [openHAB 2 FAQs at community.openhab.org](https://community.openhab.org/t/frequently-asked-questions/17727)
 
-{% include contribution-wanted.html %}
+::: tip Contribution Wanted
+Please help us improve the documentation!
+If you'd like to leave corrections, additions or comments for this article or any other part of this website, please drop a word at:
+[Documentation Issue Tracker](https://github.com/openhab/openhab-docs/issues) or open a new PR.
+:::

concepts/rules.md

@@ -266,7 +266,7 @@ Helper Libraries simplify the interaction with the openHAB runtime by providing
 By providing this functionality, they help avoid type errors and heavily reduce the amount of boilerplate code required to import and use openHAB classes.
 
 Sometimes the helper library will come with the add-on, e.g. [JS Scripting](/addons/automation/jsscripting) with the [openhab-js](https://github.com/openhab/openhab-js) library.
-Other times the helper library must be installed separately, searching in the community form might help.
+Other times the helper library must be installed separately, searching in the community forums might help.
 
 ## Comprehensive Examples
 
@@ -625,7 +625,7 @@ rule "Window open reminder" do
   changed gWindows.members, to: OPEN, for: 1.hour
   run do |event|
     # Item guaranteed to be OPEN here, no need to check
-    notify("#{event.item.label} is open for an hour!")
+    Notification.send("#{event.item.label} is open for an hour!")
   end
 end
 ```

configuration/actions.md

@@ -234,40 +234,9 @@ See [Transformations]({{base}}/configuration/transformations.html#usage) for ava
 
 ## Cloud Notification Actions
 
-Notification actions may be placed in Rules to send alerts to mobile devices registered with an [openHAB Cloud instance](https://github.com/openhab/openhab-cloud) such as [myopenHAB.org](https://myopenhab.org).
-Three different actions are available:
+Notification actions may be placed in Rules to send alerts to mobile devices registered with an [openHAB Cloud instance](https://github.com/openhab/openhab-cloud) such as [myopenHAB.org](https://www.myopenhab.org).
 
-- `sendNotification(emailAddress, message)`: Sends a notification to a specific cloud instance user
-- `sendBroadcastNotification(message)`: Sends a notification to _all_ devices of _all_ users
-- `sendLogNotification(message)`: Sends a log notification to the `notifications` list at your openHAB Cloud instance.  Notifications are NOT sent to any registered devices
-
-For each of the three actions, there's another variant accepting an icon name and a severity:
-
-- `sendNotification(emailAddress, message, icon, severity)`
-- `sendBroadcastNotification(message, icon, severity)`
-- `sendLogNotification(message, icon, severity)`
-
-Icon and severity can potentially be used by cloud instance clients (such as the openHAB apps for Android or iOS) to be displayed in the list of notifications.
-
-The parameters for these actions have the following meaning:
-
-- `emailAddress`: String containing the email address the target user is registered with in the cloud instance
-- `message`: String containing the notification message text
-- `icon`: String containing the icon name (as described in [Items]({{base}}/configuration/items.html#icons))
-- `severity`: String containing a description of the severity of the incident
-
-### Example
-
-```javascript
-rule "Front Door Notification"
-when
-  Item Apartment_FrontDoor changed to OPEN
-then
-  sendNotification("[email protected]", "Front door was opened!")
-end
-```
-
-For information on making use of the [openHAB Cloud service](https://github.com/openhab/openhab-cloud/blob/main/README.md) hosted by the [openHAB Foundation e.V.](https://www.openhabfoundation.org/), visit the [myopenhab.org website](https://www.myopenhab.org).
+Please head over to [openHAB Cloud Connector: Cloud Notification Actions](/addons/integrations/openhabcloud/#cloud-notification-actions) to learn about the notification actions and check out the examples.
 
 ## Ephemeris
 

configuration/items.md

@@ -12,10 +12,6 @@ Items can be Strings, Numbers, Switches or one of a few other basic [Item types]
 A programmer can compare Item types with base variable data types of a programming language.
 
 A unique feature of openHAB Items is the ability to connect them to the outside world via [Bindings](/addons/#binding).
-An Item does not simply store information that is set by software (e.g., `OFF`, 3.141 or "No Error"); the information stored by an Item may also be set by actions that take place in your home.
-
-But let's not get ahead of ourselves.
-The rest of this page contains details regarding Items and is structured as follows:
 
 [[toc]]
 
@@ -66,7 +62,7 @@ Switch Kitchen_Light "Kitchen Light" {channel="mqtt:topic:..." }
 String Bedroom_Sonos_CurrentTitle "Title [%s]" (gBedRoom) {channel="sonos:..."}
 Number:Power Bathroom_WashingMachine_Power "Power [%.0f W]" <energy> (gPower) {channel="homematic:..."}
 
-Number:Temperature Livingroom_Temperature "Temperature [%.1f °C]" <temperature> (gTemperature, gLivingroom) ["TargetTemperature"] {knx="1/0/15+0/0/15"}
+Number:Temperature Livingroom_Temperature "Temperature [%.1f °C]" <temperature> (gTemperature, gLivingroom) ["Setpoint", "Temperature"] {knx="1/0/15+0/0/15"}
 ```
 
 The last example above defines an Item with the following fields:
@@ -77,7 +73,7 @@ The last example above defines an Item with the following fields:
 - Item [state formatted](#state-presentation) to display temperature in Celsius to one-tenth of a degree -  for example, "21.5 °C"
 - Item [icon](#icons) with the name `temperature`
 - Item belongs to [groups](#groups) `gTemperature` and `gLivingroom` (definition not shown in the example)
-- Item is [tagged](#tags) as a thermostat with the ability to set a target temperature ("TargetTemperature")
+- Item is [tagged](#tags) as a thermostat with the ability to set a target temperature ("Setpoint", "Temperature")
 - Item is [bound to](/addons/#binding) the openHAB Binding `knx` with binding specific settings ("1/0/15+0/0/15")
 
 The remainder of this article provides additional information regarding Item definition fields.
@@ -554,11 +550,12 @@ The last Group counts all members of it matching the given regular expression, h
 
 Tags added to an Item definition allow a user to characterize the specific nature of the Item beyond its basic Item type.
 Tags can then be used by add-ons to interact with Items in context-sensitive ways.
-Tags are used by the [Semantic Model]({{base}}/tutorial/model.html).  The `"Light"` example below maps the item to the Semantic Model.
+Tags are used by the [Semantic Model]({{base}}/tutorial/model.html).
+The `"Light"` example below maps the item to the Semantic Model.
 
 Example:
 A Light in a typical home setup can be represented by a Switch, a Dimmer or a Color Item.
-To be able to interact with the light device via a natural voice command, for example, the fact that the Item is a light can be established by adding the "Lighting" tag as shown below.
+To be able to interact with the light device via a natural voice command, for example, the fact that the Item is a light can be established by adding the "Light" tag as shown below.
 
 ```java
 Switch Livingroom_Light "Livingroom Ceiling Light" ["Light"]