Add 1.20.0 documentation release

Author: wborn

versioned_docs/version-1.20.0/architecture/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Architecture",
+  "position": 6,
+  "link": {
+    "type": "generated-index"
+  }
+}

versioned_docs/version-1.20.0/architecture/apps-and-consoles.md

@@ -0,0 +1,88 @@
+---
+sidebar_position: 4
+---
+
+# Asset location tracking
+
+## Terminology
+### Asset and asset location
+Asset in the scope of this document refers specifically to assets that have a geographical location and asset location refers to a well known attribute called location which is defined on the asset; how the location is updated is specific to the asset type and whether the location attribute is linked to a protocol. Some example scenarios: -
+
+* **GPS Tracker** - A GPS tracker with internet connection (dedicated device, smart phone/watch, etc); the device pushes its location to the server, an asset is used to represent the tracker and its location is updated when an update is received from the physical device. Provides fine grained location data and following concerns must be considered:
+
+  1. Data/battery usage
+  2. Privacy issues
+  3. Storage of data (current and historical)
+
+* **Smart device with geofence APIs (e.g. Android/iOS)** - A smart device such as a mobile phone (e.g. Android or iOS) that has a geofence API for coarse location tracking; geofences are defined on the device and a callback is triggered when the geofence is:
+
+  1. Entered
+  2. Exited
+  3. Entered and Exited
+
+* **A plain old asset** - Any asset that doesn't actively monitor its location but instead the location is manually updated by a user or via a protocol.
+
+
+## Location tracking scenarios
+Reasons/use cases for location tracking:
+
+1. Showing an asset on a map
+2. Performing some action (e.g. send a notification) when an asset enters/exits a specific region
+3. Recording historical location data (privacy issues need consideration and any users should be fully aware)
+
+Scenario 3 is not in the scope of this document and will be ignored; scenario 1 can be achieved by simply plotting the asset on a map and subscribing to location attribute event changes for that asset and updating the map accordingly. Scenario 2 is essentially location triggered rules and is discussed below.
+
+## Location triggered rules
+The common use case is to specify a geographical region and to then perform some action when this region is entered, exited or both, this is known as geofencing. It is possible to define location predicates (geofences) in rule LHS and how this is implemented on the affected assets is abstracted away by the OpenRemote manager (i.e. the manager determines whether or not geofence APIs can be used or not - see below). 
+
+### Geofence API vs location updates 
+Depending on the asset type/capabilities and the specific project requirements an asset can either continually send location `attribute events` to the manager or the manager could instruct the asset to update its geofence definitions and then the asset notifies the manager when geofences are triggered. Whenever possible geofence APIs on the physical asset should be preferred for efficiency reasons; rules used to determine geofence usage:
+
+1. Asset must support geofence APIs and backend must be able to supply them in required format (specific geofence API adapters - Android/iOS geofence processing can be done in code on those devices but some things like a GPS tracker might not be able to run custom code - have to send SMS for example in specific format)
+2. Asset must support a mechanism for pushing geofences to it (geofence definition update - could be a direct mechanism or could be indirect e.g. push notification telling asset to update geofences)
+
+### Assets added/modified
+1. Asset is provisioned in the manager (either manually or automatically via a protocol)
+2. Asset type and attributes indicate geofence API support (which API and version)
+3. Any pre-existing rules that apply to this asset that have location predicates in LHS are then 'pushed' to the asset
+
+### Rules with location predicate added/modified
+1. When rules with location predicates are created and/or updated then any existing affected assets that support geofence APIs are notified and expected to update their geofence definitions
+
+### Geofence push and retrieval
+How geofences are 'pushed' to assets is handled by GeofenceAdapters that are loaded at runtime using the ServiceLoader mechanism; there is also a JAX-RS endpoint `rules/geofences/{assetId}` that allows assets to pull their geofence definitions when desired (assets that have been offline could call this endpoint to ensure their geofences are up to date, etc.). The structure of the geofence definitions returned by the endpoint is determined by the requested GeofenceAdapter (see below).
+
+### Unsupported assets/rules
+If there are rules with location predicates but they cannot be implemented using geofence APIs on the asset and/or the asset doesn't support geofence APIs then the location attribute is expected to be updated using some other mechanism (asset pushes location, protocol polling, manual, etc.)
+
+### Geofence trigger behaviour
+When a geofence is triggered on an asset then the asset should update its own location by posting to the public endpoint `asset/public/{assetId}/updateLocation`, the location value sent should be as follows:
+
+* Geofence Enter - Send geofence centre point as location (centre point should have been provided in the geofence definition retrieved from the backend)
+* Geofence Exit - Send null (this will clear the devices location and indicate that the asset has left the geofence)
+
+**By using geofence triggers in this way the handling of all location tracked assets can be processed in the same way i.e. the manager rules can compare location asset state changes irrespective of how the asset provides the location data.**
+
+## Geofence Asset Adapters
+Refer to the source code for details of the [GeofenceAssetAdapter](https://github.com/openremote/openremote/blob/location/manager/src/main/java/org/openremote/manager/rules/geofence/GeofenceAssetAdapter.java) and how it is used. Currently there is one implementation:
+
+### ORConsoleGeofenceAssetAdapter (Android and iOS consoles)
+An asset will use this adapter if it matches the following criteria:
+* Asset type: `console`
+* Has an attribute called `consoleProviders` whose value contains a console provider with a name of `geofence` and `version` value of `ORConsole`
+
+**This adapter only supports radial geofences (Android and iOS only support this type)**
+
+The geofence definitions returned by this adapter (returned by calling the `api/{realm}/rules/geofences/{assetId}`) endpoint are as follows:
+
+```json
+[
+   {
+      id: "23123abd343fed23425d", [unique ID made up from assetId and hashcode of lat, lng and radius]
+      lat: 52.0, [latitude of centre point]
+      lng: 0.0, [longitude of centre point]
+      radius: 100 [size of radial zone in m]
+      postUrl: "{realm}/asset/location/{assetId}"
+   }
+]
+```

versioned_docs/version-1.20.0/architecture/asset-location-tracking.md

@@ -0,0 +1,107 @@
+---
+sidebar_position: 5
+---
+
+# ESP32 devices
+
+Many IoT devices are or can be based on an ESP32 microcontroller.  
+A typical setup for integrating such a device in the OpenRemote ecosystem includes 3 components:
+- a firmware running on the ESP32 MCU in the device
+- a mobile app to configure the device and connect to the backend
+- the OpenRemote backend
+
+```mermaid
+graph LR
+    %% Styling Definitions
+    classDef greenStyle fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#000;
+    classDef innerGreenStyle fill:#e8f5e9,stroke:#28a745,stroke-width:1px,color:#000;
+    classDef orangeStyle fill:#ffe0b2,stroke:#f57c00,stroke-width:2px,color:#000;
+    classDef redStyle fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000;
+    classDef purpleStyle fill:#e1bee7,stroke:#7b1fa2,stroke-width:2px,color:#000;
+
+    App[App]:::orangeStyle
+
+    OR[Backend]:::greenStyle
+    
+    ESP[Device]:::purpleStyle
+
+    %% Connections
+    App <--> OR
+    App <--> ESP
+    ESP <--> OR
+```
+
+We offer software elements to support the development of all 3 components.
+
+A device is represented in the OpenRemote backend by an asset of a specific type.
+The device communicates with OpenRemote over MQTTS, authenticated with a dedicated service user.
+
+In this typical use case, the device uses Wi-Fi for its internet connectivity.
+
+To integrate a new device into the system, it needs to be provisioned.  
+This can either be done automatically, see [User Guide Auto provisioning](/user-guide/gateways-and-devices/auto-provisioning.md)  
+or through a manual process performed by the end-user.
+
+For the latter case, the workflow is as follows
+
+```mermaid
+sequenceDiagram
+    autonumber
+    
+    Note over User,Backend: User login
+    
+    User->>App: Login
+    App->>Backend: Authenticate user
+    Backend-->>App: Authenticated
+    
+    Note over User,Backend: Device Wi-Fi provisioning
+    
+    User->>Device: Put in discovery mode
+    App->>App: Start device scan
+    Device-->>App: Device name
+    User->>App: select device
+    App->>App: Stop device scan
+    App->>Device: Connect
+    Device->>App: Get PoP
+    App-->>Device: PoP
+    App->>Device: Start Wi-Fi scan
+    Device-->>App: Wi-Fi information
+    User->>App: Select Wi-Fi (or join other)
+    User->>App: Enter Wi-Fi password
+    App->>Device: Wi-Fi configuration
+    Device->>App: Wi-Fi connection status
+    
+    Note over User,Backend: Device provisioning
+    
+    App->>Device: Get Device Id (DeviceInfo Request)
+    Device-->>App: Device Id (DeviceInfo Response)
+    
+    App->>App: Create password
+    App->>Backend: Provision device
+    Note right of App: App provides Device Id and password
+    
+    Backend->>Backend: Create Device Asset
+    Note right of Backend: Asset is linked to user account
+    
+    Backend->>Backend: Create Service Account
+    Note right of Backend: Service Account is restricted<br/>and only has rights on the Device Asset.<br/>username is Device Id
+    
+    Backend-->>App: Confirmed
+    Note right of Backend: Returns Asset Id
+    
+    App->>Device: Send configuration (OpenRemoteConfig Request)
+    Device->>Backend: connect
+    Note right of Device: Over MQTTS using username/password<br/>(Service Account)
+    
+    Device-->>App: Status (OpenRemoteConfig Response)
+    App->>Device: Get connection status (BackendConnectionStatus Request)
+    Device-->>App: connection status (BackendConnectionStatus Response)
+    Note right of Device: Repeat to poll for connected status  
+```
+
+Communication between the Mobile Application and the Device is based on Espressif [Unified Provisioning](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/provisioning/provisioning.html).  
+This mechanism is used to discover the device, then establish a secure communication channel over BLE.  
+Communication on this channel uses Protocol Buffer payloads, in addition to the messages defined by Espressif, OpenRemote uses messages defined in the following ProtoBuf spec: [ORConfigChannelProtocol](https://github.com/openremote/console-ios-lib/blob/7212bc905c7df34c2f3d62f801f0e4df7529a2f0/ORLib/ORConfigChannelProtocol.proto)  
+OpenRemote includes the [ESP Provision provider](apps-and-consoles.md#esp-provision-provider-espprovision) to support the implementation of the mobile application side.
+
+On the backend, the project must implement a single `/rest/device` endpoint, see [Provision Device API](../provisioning-api/provision-device.api.mdx) for more details.

versioned_docs/version-1.20.0/architecture/esp32-device.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 1
+---
+
+# Manager endpoints and file paths
+
+## Endpoints
+
+The OpenRemote Manager exposes the following endpoints:
+
+* `/` - Redirects to redirect path (set by `ROOT_REDIRECT_PATH` default: `/manager`)
+* `/manager` - Manager UI app (loaded from `$APP_DOCROOT` see paths below)
+* `/console_loader` - Loader UI app used by iOS and Android consoles (loaded from `$APP_DOCROOT` see paths below)
+* `/swagger` - Swagger UI app (loaded from `$APP_DOCROOT` see paths below)
+* `/shared` - Shared UI resources (fonts, locale files, map sprites, icons, etc.) (loaded from `$APP_DOCROOT` see paths below)
+* `/api` - HTTP API (see swagger endpoint for live documentation)
+* `/auth` - Keycloak reverse proxy endpoint
+* `/websocket` - WebSocket endpoint
+* `/*` - Any other path is resolved against `$CUSTOM_APP_DOCROOT` (see paths below)
+* `/manager_config.json` - File that is loaded by the Manager UI to apply custom configuration to the Manager UI (white labelling, menu config, etc.)  (loaded from `$CUSTOM_APP_DOCROOT`) (see [here](../user-guide/deploying/configuring-the-manager-ui.md) for more details)
+* `/locales` - Path used by Manager UI to find custom `i18n` locale files, each locale should be in it's own directory with a file named `app.json` (e.g. `/locales/en/app.json`) (loaded from `$CUSTOM_APP_DOCROOT`)
+
+### App Realm
+Generally applications are linked to a specific realm which cannot be changed but apps can support multiple realms (like the Manager UI), in this instance the app can either present a list of realms for the user to select and/or the app could support setting the realm via a query parameter; which is what the Manager UI currently does:
+
+e.g.  `/manager/?realm=smartcity`
+
+## File paths
+
+The following list shows the file paths used by our Docker containers; these can be customised by changing environment variable values (where a file path is controlled by an environment variable) and/or by using volume mapping, this is how we provide customised instances of our system for specific projects. The default values shown below are the defaults as used by our Docker containers.
+
+### Manager
+
+* `$OR_APP_DOCROOT` - Location of well known UI apps and shared resources; Default: `/opt/web`
+* `$OR_CUSTOM_APP_DOCROOT` - Location used to load paths that aren't well known which allows custom web content to be served; Default: `/deployment/manager/app`
+* `$OR_FIREBASE_CONFIG_FILE` - Location of Firebase Cloud Messaging configuration file which allows push notification functionality `/deployment/manager/fcm.json`
+* `$OR_KEYCLOAK_GRANT_FILE` - Location of [OAuth Grant](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/auth/OAuthGrant.java) in `json` representation which is used internally by the manager to communicate with Keycloak (in order to provision users, tenants, etc.); Default: `/deployment/manager/keycloak.json`
+* `$OR_LOGGING_CONFIG_FILE` - Path of custom `JUL` logging config file; Default: `/deployment/manager/logging.properties`, falls back to built-in config if not specified or not found which can be found [here](https://github.com/openremote/openremote/blob/master/manager/src/main/resources/logging.properties).
+* `$OR_MAP_TILES_PATH` - Path of `mbtiles` map data file; Default: `/deployment/map/mapdata.mbtiles`, falls back to built-in map data (`/opt/map/mapdata.mbtiles`) if not specified or not found which can be found [here](https://github.com/openremote/openremote/tree/master/manager/src/map)
+* `$OR_MAP_SETTINGS_PATH` - Map settings path to `json` configuration for styling the map; Default: `/deployment/map/mapsettings.json`, falls back to built-in settings (`/opt/map/mapsettings.json`) if not specified or not found which can be found [here](https://github.com/openremote/openremote/tree/master/manager/src/map)
+* `/deployment/manager/extensions` - Location of custom java code that is added to the classpath of the manager during startup
+* `$OR_PROVISIONING_DOCROOT` - Location of provisioning directory which can contain the following sub-directories of `json` representations to be automatically provisioned into the manager during a clean install setup:
+  * `assets` - Sorted alphabetically, each `json` file should contain exactly 1 asset in `json` representation
+  * `consoleappconfig`- Each `json` file should contain exactly 1 [ConsoleAppConfig](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/apps/ConsoleAppConfig.java) in `json` representation