Updates of Tutorials and adding new ones

docs/tutorials/auto-provision-devices-at-scale.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 8
+---
+
+# Auto-provision and onboard OEM devices at scale
+
+If you build and distribute your own hardware, you do not want to register every unit by hand. This tutorial shows how **auto-provisioning** lets a device **self-register** the first time it connects: OpenRemote authenticates it, creates an **asset** of the type you defined, and links its **attributes** to the right MQTT topics — true **zero-touch device onboarding**.
+
+:::tip Why this matters for OEMs and integrators
+Provisioning in OpenRemote creates the client credentials **and** the digital asset **and** the attribute links in a single flow, included in the open-source core. That means a freshly flashed device becomes a fully modelled, queryable asset the moment it powers on in the field.
+:::
+
+## Prerequisites
+
+- A running OpenRemote instance — see the [Quick Start](https://docs.openremote.io/docs/quick-start).
+- Superuser access to a realm where your devices will live.
+- A device (or test client) that can do MQTT over TLS with an X.509 client certificate — for example an ESP32/ESP8266.
+
+## Step 1 — Define the asset type your device represents
+
+Decide what each device *is* in your model (e.g. a `Thing`, or a custom `EnvironmentSensor` asset type from a custom project). The provisioning flow will create one asset of this type per device, so model the attributes you want populated (temperature, humidity, battery, etc.).
+
+## Step 2 — Create a provisioning configuration
+
+1. Go to the **Provisioning** configuration for your realm (Manager UI).
+2. Create an **X.509 provisioning config** and paste the **CA certificate** that signed your device certificates.
+3. Select the **asset type** to create per device and set the realm.
+4. Choose whether to **auto-link attributes** to standard MQTT topics and whether newly provisioned assets are **disabled until approved** (useful for a manufacturing QA gate).
+
+See [Auto provisioning devices and users](https://docs.openremote.io/docs/user-guide/gateways-and-devices/auto-provisioning) for the message format and the full configuration reference.
+
+## Step 3 — Flash devices with a unique certificate
+
+Each unit ships with a unique client certificate signed by your CA. The device's unique ID (for example a serial number embedded in the certificate's common name) becomes the identity OpenRemote uses to create and name the asset.
+
+## Step 4 — Let the device provision itself
+
+On first connection the device publishes a provisioning request to the provisioning topic. OpenRemote validates the certificate against your CA, then:
+
+1. Creates the asset of your chosen type (if it does not already exist).
+2. Links its attributes to the device's publish/subscribe topics.
+3. Returns the asset ID so the device can start publishing telemetry immediately.
+
+For a concrete firmware example, follow [Connect ESP32 or ESP8266 using MQTT](https://docs.openremote.io/docs/user-guide/gateways-and-devices/connect-esp32-or-esp8266-using-mqtt), then point it at your provisioning config instead of a manually created service user.
+
+## Step 5 — Verify and scale
+
+1. Power on one device and confirm a new asset appears in the asset tree with live values.
+2. Power on a second unit with a different certificate and confirm a second, separate asset is created.
+3. Roll out the remaining fleet — no manual asset creation required.
+
+:::note
+Combine this with [multi-tenant realms](./white-label-multi-tenant-iot-platform) so each customer's devices provision straight into that customer's realm.
+:::
+
+## Next steps
+
+- Keep field devices current with [OTA firmware updates using hawkBit](./ota-firmware-updates-with-hawkbit).
+- Deploy a local [edge gateway with a secure tunnel](./edge-gateway-secure-tunnel) for sites with intermittent connectivity.

docs/tutorials/change-celsius-to-fahrenheit-with-flow.md

@@ -1,10 +1,16 @@
 ---
-sidebar_position: 4
+sidebar_position: 11
 ---
 
 # Celsius to Fahrenheit with Flow
 
-An example for converting an attribute value, using the Flow editor is the conversion from temperature Celsius into Fahrenheit.
+This tutorial offers an example for converting an attribute value, using the Flow editor. This example describes the conversion from temperature Celsius into Fahrenheit.
+
+## Prerequisites
+
+- A running OpenRemote instance — see the [Quick Start](https://docs.openremote.io/docs/quick-start).
+
+## Step 1 — Create a new attribute
 
 First of all create the attribute you want to show the temperature in Fahrenheit. Note that you have to add the configuration item “Rule state” to be able to use it in the flow editor. In the example we also:
 
@@ -15,6 +21,8 @@ First of all create the attribute you want to show the temperature in Fahrenheit
 
 ![Add Fahrenheit attribute](img/flow-new-attribute-for-flow.png)
 
+## Step 2 — Create the flow rule
+
 Next create a flow in the flow editor, which looks like this:
 
 ![Flow from Celsius to Fahrenheit](img/flow-celsius-to-fahrenheit.png)

docs/tutorials/configure-mobile-app-behaviour.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 12
 ---
 
 # Configure mobile app behaviour
@@ -32,15 +32,15 @@ This file has the following structure
 }
 ```
 
-## Domain
+## Step 1 - Domain
 
 The domain must always be manually entered by the user. Users can enter:
 - a full URL (e.g. https://myapp.example.com), with optional port
 - a fully qualified host name (e.g. myapp.example.com), https in used as the scheme
 - an IP address, with or without scheme (e.g. 192.168.1.1)
 - a simple domain (string with no dot in name), the URL used is then https://_domain_.openremote.app
 
-## App
+## Step 2 - App
 
 By default, the system discovers the available apps and presents them to the user as a list for selection.  
 If there's only one available app, it's automatically selected and no option is presented to the user.
@@ -76,7 +76,7 @@ In this case, even if only one application is available, it is not automatically
 You can also specify the app to be used and forbid selection by the user (the app selection option is never presented).  
 Customize the `console_config.json` file, setting the `app` field to the name of the app you want to be used.
 
-## Realm
+## Step 3 - Realm
 
 As for apps, by default, the console presents the user with a list of possible realms for selection.  
 If there's only one available realm, it's automatically selected and no option is presented to the user.
@@ -101,7 +101,7 @@ For example
 If you don't want the console to present a list of available realms, you can force the user to manually enter the realm name in a text field.  
 Customize the `console_config.json` file, setting the `showRealmTextInput` to `true`.  
 
-## Providers
+## Step 4 - Providers
 
 For example
 ```json

docs/tutorials/connect-modbus-devices.md

@@ -0,0 +1,58 @@
+---
+sidebar_position: 5
+---
+
+# Connect Modbus TCP/RTU devices (PLCs, meters, inverters)
+
+**Modbus** is everywhere in industrial and energy hardware — PLCs, energy meters, solar inverters, HVAC controllers. This tutorial shows how to connect Modbus devices to OpenRemote running as a gateway, using the **native Modbus agent**, mapping registers straight onto **asset attributes** over Ethernet (**Modbus TCP**) or serial (**Modbus RTU**).
+
+:::tip Why this matters for OEMs and integrators
+The Modbus agent runs **inside the OpenRemote Manager** — there is no separate gateway application to deploy and operate just to speak an industrial protocol. The same is true for KNX, and SNMP and more, which keeps your **industrial IoT** architecture simple.
+:::
+
+## Prerequisites
+
+- A running OpenRemote instance — see the [Quick Start](https://docs.openremote.io/docs/quick-start).
+- A reachable Modbus device: a Modbus TCP slave on your network, or a Modbus RTU device on a serial line accessible to the Manager host.
+- The device's register map (function code, address, data type, scaling).
+
+## Step 1 — Create a Modbus agent
+
+1. On the **Assets** page, click **+** and add a **Modbus TCP Agent** (or **Modbus RTU Agent**).
+2. For TCP, set the host/IP and port (default `502`) and the unit/slave ID.
+3. For RTU, set the serial port, baud rate, parity and stop bits, and the unit ID.
+
+See the [Modbus agent reference](https://docs.openremote.io/docs/user-guide/agents-protocols/modbus) for all parameters.
+
+## Step 2 — Create the asset that represents the device
+
+Create an asset (e.g. an `ElectricityMeter` or a generic `Thing`) and add attributes for each value you want to read or write — for example `power` (number), `voltage` (number), `relayState` (boolean).
+
+## Step 3 — Link attributes to Modbus registers
+
+For each attribute, add the **Agent Link** configuration item and select your Modbus agent, then specify:
+
+- the **register type** (coil, discrete input, input register, holding register),
+- the **address**,
+- the **data type** (e.g. `INT16`, `UINT32`, `FLOAT32`),
+- the **read/write** behaviour and a **polling interval**,
+- optional **scaling** to convert raw registers into engineering units.
+
+:::note
+Writing to a holding register or coil lets you actuate the device (e.g. toggle a relay) straight from an attribute write, the Manager UI, the REST API, or a rule.
+:::
+
+## Step 4 — Verify live data
+
+1. Open the asset and confirm attribute values update on each poll.
+2. Check the History panel to confirm values are being stored as time series.
+3. Test a write by changing a writable attribute and confirming the device responds.
+
+## Step 5 — Turn raw values into insight
+
+Use [Flow rules](https://docs.openremote.io/docs/user-guide/rules-and-forecasting/flow-rules) to derive virtual attributes (e.g. compute energy from power), and [When-Then rules](https://docs.openremote.io/docs/user-guide/rules-and-forecasting/when-then-rules) to alarm on thresholds.
+
+## Next steps
+
+- Deploy a local [edge gateway with a secure tunnel](./edge-gateway-secure-tunnel) for sites with intermittent connectivity.
+

docs/tutorials/connect-your-mqtt-client.md

@@ -1,12 +1,12 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Connect your MQTT Client
 
 In this tutorial we will use the [MQTT API](../user-guide/manager-apis.md#mqtt-api-mqtt-broker) to subscribe to changes of asset attributes values and publish data to them from a MQTT Client. The OpenRemote Manager functions as the MQTT Broker. You can use a desktop MQTT client (e.g. [MQTT Explorer](https://mqtt-explorer.com/) or [MQTT X](https://mqttx.app/)) for this tutorial, or better yet the device you want to connect.
 
-## Create an asset with attributes
+## Step 1 - Create an asset with attributes
 We will create a Thing asset, but feel free to use an AssetType that matches your physical device
 1. On the assets page, click the `+` in the asset tree on the left
 1. Select the Thing asset type, give it a friendly name and click 'Add'
@@ -20,30 +20,30 @@ We will create a Thing asset, but feel free to use an AssetType that matches you
       - name: `writeAttribute`
       - Valuetype: `Number`
 
-## Create a service user
+## Step 2 - Create a service user
 The service user will give programmatic access to the MQTT client.
 1. Go to the users page and create a new service user (second panel on the page)
 2. Name the service user `mqttuser` and give the user the read and write role for the sake of convenience. It is advised to configure a more restricted role for your service users.
 3. Click 'Create', a secret will be generated automatically.
 4. Open the 'mqttuser' user to see and copy the secret
 
-## Establish a connection from client to broker
+## Step 3 - Establish a connection from client to broker
 In your MQTT client set up a new connection:
 - host: `mqtt://localhost` (or URL of your hosted environment e.g. demo.openremote.io)
 - Port: `8883` with TLS/SSL enabled; most clients will work with our self generated Let's Encrypt certificates, but if using a self signed certificate or your client isn't able to validate the cert chain then you may need to explicitly load the cert into your client or disable/relax the client's TLS verification settings (refer to your specific client's documentation). It is possible to expose the broker un-encrypted on port `1883` by creating a port mapping for that on the `manager` service in your Docker Compose file
 - password: the secret generated for the MQTT service user (you can find it on the mqttuser users page)
 - username: `master:mqttuser` (`{realm}:{user}`)
-- clientID: `client123` (this can be anything you like but must be unique - Any existing connection with the same client ID will be replaced. Make sure this clientID remains identical.)
+- clientId: `client123` (this can be anything you like but must be unique - Any existing connection with the same client ID will be replaced. Make sure this clientId remains identical.)
 
-## Subscribe to attributes using the MQTT API
+## Step 4 - Subscribe to attributes using the MQTT API
 In this tutorial we will be looking at specific attributes of a specific asset. There are [many more options](../user-guide/manager-apis.md#mqtt-api-mqtt-broker) of subscribing to (all) updates of assets and attributes. The asset attributes that you will be subscribing to can be written by the user, by rules, or can be a live value gathered through an Agent link with another device in the field. You can imagine this boolean value could toggle a function of the device subscribed to the attribute
 1. Get the ID of the Thing asset by navigating to its asset page and copying the ID in the URL (e.g. `http://localhost:9000/manager/#!assets/false/6xIa9MkpZuR7slaUGB6OTZ` => `6xIa9MkpZuR7slaUGB6OTZ`)
 2. Create a subscription for the subscribeAttribute in your MQTT client with the topic: `{realm}/{clientId}/attribute/{attributeName}/{assetId}`. So in our case this will be `master/client123/attribute/subscribeAttribute/6xIa9MkpZuR7slaUGB6OTZ`
 3. In the view mode of the Thing asset in the OpenRemote Manager, write a new value to the 'Subscribe attribute' by clicking the checkbox.
 4. Verify that you see the value (`true`/`false`) coming in on your MQTT client!
 
-## Publish attribute values from the MQTT client
+## Step 5 - Publish attribute values from the MQTT client
 You can publish data from your MQTT client (device) to the OpenRemote manager so that you can monitor the device and create rules.
-1. Define the correct topic. For directly writing an attribute value: `{realm}/{clientID}/writeattributevalue/{attributeName}/{assetID}`. So in our case this will be `master/client123/writeattributevalue/writeAttribute/6xIa9MkpZuR7slaUGB6OTZ`
+1. Define the correct topic. For directly writing an attribute value: `{realm}/{clientId}/writeattributevalue/{attributeName}/{assetId}`. So in our case this will be `master/client123/writeattributevalue/writeAttribute/6xIa9MkpZuR7slaUGB6OTZ`
 2. Send the JSON over this topic. For a Number, this is really simple: `23`
 3. Go to the Manager and check if the value updated!

docs/tutorials/edge-gateway-secure-tunnel.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 7
+---
+
+# Deploy OpenRemote as an edge gateway with a secure tunnel
+
+For sites with intermittent connectivity, local control loops or data-residency requirements, you want compute at the edge. This tutorial shows how to run OpenRemote as an **edge gateway**, link it to a **central** instance, and **remotely access** the on-site gateway through a **secure tunnel** — a hybrid **on-premise** plus cloud architecture.
+
+:::tip Why this matters for integrators
+The edge gateway is the **same OpenRemote codebase** running on-site, so an instance can act as both server and gateway — the asset model, agents and rules you already know run locally too. Gateway UIs can be reached from the central instance over a secure tunnel for remote maintenance.
+:::
+
+## Prerequisites
+
+- Two OpenRemote instances: a **central** instance and an on-site **edge** instance (both from the [Quick Start](https://docs.openremote.io/docs/quick-start) / Docker images; `amd64` and `arm64` are supported, so the edge can run on small hardware).
+- Network access from the edge instance out to the central instance.
+- Read [OpenRemote as Edge Gateway](https://docs.openremote.io/docs/user-guide/gateways-and-devices/edge-gateway).
+
+## Step 1 — Run OpenRemote on the edge
+
+Deploy a standard OpenRemote instance on the on-site hardware. Connect your local devices to it using whichever agents fit — [Modbus](./connect-modbus-devices), [KNX](../user-guide/agents-protocols/knx), MQTT, Z-Wave, etc. The edge instance keeps working and storing data even if the uplink drops.
+
+## Step 2 — Register the gateway on the central instance
+
+1. On the **central** Manager, create a **Gateway** asset/connection for the site.
+2. This issues credentials the edge instance uses to authenticate its outbound connection.
+
+## Step 3 — Connect the edge to the central instance
+
+Configure the edge instance with the central instance's address and the gateway credentials. Once connected, the site's assets become visible and manageable from the central instance, while continuing to run locally.
+
+## Step 4 — Remotely access the gateway UI via the secure tunnel
+
+Open the gateway's local UI from the central instance through the **secure tunnel**, so field engineers can configure and troubleshoot a site without a site visit or a public inbound port. Follow the tunnel setup in [OpenRemote as Edge Gateway](https://docs.openremote.io/docs/user-guide/gateways-and-devices/edge-gateway).
+
+:::caution
+Restrict who can open tunnels and access gateway UIs using [roles and restricted users](./enterprise-identity-sso-rbac); remote access to field equipment should be tightly scoped.
+:::
+
+## Step 5 — Decide what runs where
+
+Keep latency-sensitive control and local automation in [edge rules](https://docs.openremote.io/docs/user-guide/rules-and-forecasting/create-rules), and use the central instance for cross-site dashboards, fleet-wide rules and long-term analytics.
+
+## Next steps
+
+- Push [OTA firmware updates](./ota-firmware-updates-with-hawkbit) to devices behind the gateway.
+- Onboard edge devices automatically with [auto-provisioning](./auto-provision-devices-at-scale).