From 4aab7f501de35b27418a1fa73a07ce604f153854 Mon Sep 17 00:00:00 2001 From: Wouter Born Date: Mon, 16 Sep 2024 13:41:39 +0200 Subject: [PATCH] Add REST API links, remove unnecessary categories, fix typos (#9) Fixes #8 --- docs/introduction.md | 2 +- docs/quick-start.md | 2 +- .../configure-mobile-app-behaviour.md | 8 ++--- docs/tutorials/connect-your-mqtt-client.md | 4 +-- .../disabled-protocols/artnet-dmx-agent.md | 2 +- .../ikea-tr\303\245dfri-agent.md" | 2 +- .../or-controller-2.5-agent.md | 2 +- docs/user-guide/agents-protocols/email.md | 2 +- docs/user-guide/agents-protocols/lora.md | 2 +- docs/user-guide/agents-protocols/mqtt.md | 4 +-- docs/user-guide/agents-protocols/overview.md | 8 ++--- .../agents-protocols/partner-integrations.md | 2 +- docs/user-guide/agents-protocols/z-wave.md | 36 +++++++++---------- docs/user-guide/anomaly-detection.md | 8 ++--- .../assets-agents-and-attributes.md | 30 ++++++++-------- .../assets-and-attributes/_category_.json | 7 ---- .../deploying/aws-cloudformation.md | 4 +-- .../user-guide/deploying/balena-deployment.md | 2 +- .../deploying/configuring-the-manager-ui.md | 4 +-- .../create-your-energy-management-system.md | 8 ++--- .../gateways-and-devices/auto-provisioning.md | 16 ++++----- .../connect-esp32-or-esp8266-using-mqtt.md | 6 ++-- .../gateways-and-devices/edge-gateway.md | 6 ++-- .../realms-users-and-roles.md | 10 +++--- .../{manager-apis => }/manager-apis.md | 12 ++++--- docs/user-guide/manager-apis/_category_.json | 7 ---- docs/user-guide/manager-ui/manager-ui.md | 26 +++++++------- docs/user-guide/manager-ui/on-mobile.md | 4 +-- docusaurus.config.ts | 13 ++++--- 29 files changed, 113 insertions(+), 126 deletions(-) rename docs/user-guide/{assets-and-attributes => }/assets-agents-and-attributes.md (68%) delete mode 100644 docs/user-guide/assets-and-attributes/_category_.json rename docs/user-guide/{manager-apis => }/manager-apis.md (92%) delete mode 100644 docs/user-guide/manager-apis/_category_.json diff --git a/docs/introduction.md b/docs/introduction.md index ad85b30..db3bc4c 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -31,7 +31,7 @@ The OpenRemote [Frontend](developer-guide/working-on-ui-and-apps.md) simplifies We support the latest HTML standards and provide [web components](https://github.com/openremote/openremote/tree/master/ui/component) to build applications quickly, utilising the OpenRemote asset model and APIs: you can easily show all your assets on a map, for example. [Full web applications](https://github.com/openremote/openremote/tree/master/ui/app) are also bundled with OpenRemote, these can be used as templates for building custom web applications. -The OpenRemote [Android](https://github.com/openremote/console-android) and [iOS](https://github.com/openremote/console-ios) Consoles are native mobile applications that act as a shell for web applications built with the OpenRemote web components; a web browser is also considered to be a console and we automatically integrate native console features like push notifications and geo-fencing on each platform. If you have an existing website, add OpenRemote web components and wrap it in the OpenRemote console to connect your mobile users to your IoT network. +The OpenRemote [Android](https://github.com/openremote/console-android) and [iOS](https://github.com/openremote/console-ios) Consoles are native mobile applications that act as a shell for web applications built with the OpenRemote web components; a web browser is also considered to be a console and we automatically integrate native console features like push notifications and geofencing on each platform. If you have an existing website, add OpenRemote web components and wrap it in the OpenRemote console to connect your mobile users to your IoT network. Security is paramount when it comes to IoT and out of the box the manager integrates with [Keycloak](https://www.keycloak.org/) to provide industry standard multi-tenant authentication; out of the box we also provide TLS/SSL when using our HAProxy-based reverse proxy. diff --git a/docs/quick-start.md b/docs/quick-start.md index 8f46fb5..8d73c3d 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -67,7 +67,7 @@ For information and how to set up a development environment, see the [Developer We work with Java, Groovy, TypeScript, Gradle, Docker, and a wide range of APIs and protocol implementations. -We follow the [Github Flow](https://docs.github.com/en/get-started/quickstart/github-flow) workflow with tags and releases for published versions of our components; when working on the codebase create descriptive branch names (e.g. `feature/cool_feature_x`, `hotfix/flux_capacitor`, `issue/123`, etc.). +We follow the [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) workflow with tags and releases for published versions of our components; when working on the codebase create descriptive branch names (e.g. `feature/cool_feature_x`, `hotfix/flux_capacitor`, `issue/123`, etc.). When your changes are complete then create a Pull Request ensuring that your branch is up-to-date with the source branch and that code changes are covered by tests and that the full test suite passes. diff --git a/docs/tutorials/configure-mobile-app-behaviour.md b/docs/tutorials/configure-mobile-app-behaviour.md index a01afdd..a2ef1c4 100644 --- a/docs/tutorials/configure-mobile-app-behaviour.md +++ b/docs/tutorials/configure-mobile-app-behaviour.md @@ -9,10 +9,9 @@ T.B.D. Here we will explain how to configure your apps to be used in the OpenRemote mobile app. You have the option to show/not show on mobile, and for which realms the app is available. Also you can define whether realm options are shown as a list or input field (if you don't want to reveal all available realms). Mobile apps can be found in the -[Apple Appstore](https://apps.apple.com/nl/app/openremote-app/id1526315885?mt=8) and [Google Playstore](https://play.google.com/store/apps/details?id=io.openremote.app&pcampaignid=pcampaignidMKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1) +[Apple App Store](https://apps.apple.com/nl/app/openremote-app/id1526315885?mt=8) and on [Google Play](https://play.google.com/store/apps/details?id=io.openremote.app&pcampaignid=pcampaignidMKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1). -The first time opening the app you will be asked three things: 'App Domain', 'Select an app' and 'Enter the Realm'. Switching between domains, apps and realms can be done by long-pressing the app icon on your home screen. If you are hosting an OpenRemote instance at https://yourhost.com use the following: 'App Domain' is 'yourhost.com'.
-
+The first time opening the app you will be asked three things: 'App Domain', 'Select an app' and 'Enter the Realm'. Switching between domains, apps and realms can be done by long-pressing the app icon on your home screen. If you are hosting an OpenRemote instance at https://yourhost.com use the following: 'App Domain' is 'yourhost.com'. ## Configure apps which can be selected @@ -25,8 +24,7 @@ The `allowedApps` field allows you to customize the list of apps that is visible For example: `{ allowedApps: ['manager', 'custom'] }` Both of these options only impact the consoles, the URLs are still available on the web.
-If during use only one App is present, the consoles will automatically skip the 'app selection'-menu, and go straight to the app.
-
+If during use only one App is present, the consoles will automatically skip the 'app selection'-menu, and go straight to the app. ## Configure for which realms the app can be used diff --git a/docs/tutorials/connect-your-mqtt-client.md b/docs/tutorials/connect-your-mqtt-client.md index b83f261..b1e190f 100644 --- a/docs/tutorials/connect-your-mqtt-client.md +++ b/docs/tutorials/connect-your-mqtt-client.md @@ -4,7 +4,7 @@ sidebar_position: 2 # Connect your MQTT Client -In this tutorial we will use the [MQTT API](../user-guide/manager-apis/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. +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 We will create a Thing asset, but feel free to use an AssetType that matches your physical device @@ -36,7 +36,7 @@ In your MQTT client set up a new connection: - 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 -In this tutorial we will be looking at specific attributes of a specific asset. There are [many more options](../user-guide/manager-apis/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 +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. diff --git a/docs/user-guide/agents-protocols/disabled-protocols/artnet-dmx-agent.md b/docs/user-guide/agents-protocols/disabled-protocols/artnet-dmx-agent.md index 2116d94..62c3c3d 100644 --- a/docs/user-guide/agents-protocols/disabled-protocols/artnet-dmx-agent.md +++ b/docs/user-guide/agents-protocols/disabled-protocols/artnet-dmx-agent.md @@ -95,7 +95,7 @@ This step-by-step guide requires the use of the OpenRemote Manager. To import light assets, a ArtNet Agent must have been added to the asset tree. From there, edit the ArtNet Agent's asset. By collapsing the "ArtnetProtocolAgent" protocol configuration, you will be able to import Light assets in the "Protocol link import/discovery" attribute. -Before importing the JSON, an 'parent' asset must be targeted to where the lights will be appended to. We recommend to choose the same asset to were the ArtNet Agent resides. +Before importing the JSON, a 'parent' asset must be targeted to where the lights will be appended to. We recommend to choose the same asset to were the ArtNet Agent resides. Finally the JSON can be imported by making use of the "Upload & import links from file" button. diff --git "a/docs/user-guide/agents-protocols/disabled-protocols/ikea-tr\303\245dfri-agent.md" "b/docs/user-guide/agents-protocols/disabled-protocols/ikea-tr\303\245dfri-agent.md" index d389a56..42d5f48 100644 --- "a/docs/user-guide/agents-protocols/disabled-protocols/ikea-tr\303\245dfri-agent.md" +++ "b/docs/user-guide/agents-protocols/disabled-protocols/ikea-tr\303\245dfri-agent.md" @@ -35,7 +35,7 @@ DATABASE_CONNECTION_URL: jdbc:postgresql://localhost/openremote ## Connect an IKEA TRÅDFRI Gateway -In the following example, you link your existing IKEA TRÅDFRI Gateway by using its IP address, eg. `192.163.1.2`. +In the following example, you link your existing IKEA TRÅDFRI Gateway by using its IP address, e.g. `192.163.1.2`. 1. Login to the manager UI (`https://localhost/manager` as `admin/secret`) 2. Select the Assets tab and click `Create asset` at the top of the Asset list on the left diff --git a/docs/user-guide/agents-protocols/disabled-protocols/or-controller-2.5-agent.md b/docs/user-guide/agents-protocols/disabled-protocols/or-controller-2.5-agent.md index 3eb10a4..fc0e371 100644 --- a/docs/user-guide/agents-protocols/disabled-protocols/or-controller-2.5-agent.md +++ b/docs/user-guide/agents-protocols/disabled-protocols/or-controller-2.5-agent.md @@ -14,7 +14,7 @@ Controller Protocol is intended to connect an OpenRemote Controller 2.5 to an Op We'll explain how you can connect your own controller, or the existing Home Example Demo Controller. ## Connect an OpenRemote Controller -In the following example, you link your own controller by using the its controller address `http://my.controller:8688/controller`. +In the following example, you link your own controller by using the controller address `http://my.controller:8688/controller`. 1. Login to the manager UI (`https://localhost/manager` as `admin/secret`) 2. Select the Assets tab and click `Create asset` at the top of the Asset list on the left diff --git a/docs/user-guide/agents-protocols/email.md b/docs/user-guide/agents-protocols/email.md index 347a0ab..7c22996 100644 --- a/docs/user-guide/agents-protocols/email.md +++ b/docs/user-guide/agents-protocols/email.md @@ -4,6 +4,6 @@ sidebar_position: 3 # E-mail -OpenRemote includes an e-mail client which can connect to your mail service. Through an e-mail agent you can receive e-mails and process the text into attribute values. Based on sending address and title data get's automatically linked to the correct asset in your instance. +OpenRemote includes an e-mail client which can connect to your mail service. Through an e-mail agent you can receive e-mails and process the text into attribute values. Based on sending address and title data gets automatically linked to the correct asset in your instance. **See attributes in the Mail agent for further details on configuration** diff --git a/docs/user-guide/agents-protocols/lora.md b/docs/user-guide/agents-protocols/lora.md index 401d546..15dc5fc 100644 --- a/docs/user-guide/agents-protocols/lora.md +++ b/docs/user-guide/agents-protocols/lora.md @@ -4,7 +4,7 @@ sidebar_position: 6 # LoRa -OpenRemote supports LoRa integration. You can connect OpenRemote to the most popular LoRa network servers (eg. ChirpStack and TTN), using their documented APIs. As example we have worked out this [Tutorial: connecting to LoRaWAN sensor data from Chirpstack](../../tutorials/receive-lorawan-sensor-data-from-chirpstack.md). +OpenRemote supports LoRa integration. You can connect OpenRemote to the most popular LoRa network servers (e.g. ChirpStack and TTN), using their documented APIs. As example we have worked out this [Tutorial: connecting to LoRaWAN sensor data from Chirpstack](../../tutorials/receive-lorawan-sensor-data-from-chirpstack.md). ## Proof of concept for LoRa mesh network for GPS trackers diff --git a/docs/user-guide/agents-protocols/mqtt.md b/docs/user-guide/agents-protocols/mqtt.md index 6e6597e..9e087fb 100644 --- a/docs/user-guide/agents-protocols/mqtt.md +++ b/docs/user-guide/agents-protocols/mqtt.md @@ -7,12 +7,12 @@ sidebar_position: 7 There is an MQTT Agent (Client) in OpenRemote that you can use to connect to an external MQTT Broker. First use the MQTT Agent to establish the connection to the broker. Then create an asset with attribute(s) of the Value Type that matches the incoming/outgoing data, and give those attributes the configuration item 'Agent Link'. In this agent link select your MQTT Agent and add the parameter Publish Topic or Subscription Topic. We have no extensive documentation yet, and recommend to [check our forum](https://forum.openremote.io/t/mqtt-agents-publish-subscription/985). -OpenRemote also has an [MQTT Broker](../manager-apis/manager-apis.md#mqtt-api-mqtt-broker) (or MQTT API). +OpenRemote also has an [MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) (or MQTT API). ## See also - [Agent overview](overview.md) -- [MQTT Broker](../manager-apis/manager-apis.md#mqtt-api-mqtt-broker) +- [MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) - [Quick Start](https://github.com/openremote/openremote/blob/master/README.md) - [Manager UI Guide](../manager-ui/manager-ui.md) - [Custom Deployment](../deploying/custom-deployment.md) diff --git a/docs/user-guide/agents-protocols/overview.md b/docs/user-guide/agents-protocols/overview.md index a136ad6..dec12a7 100644 --- a/docs/user-guide/agents-protocols/overview.md +++ b/docs/user-guide/agents-protocols/overview.md @@ -10,7 +10,7 @@ sidebar_position: 1 * Generic agents (HTTP, TCP, UDP, WS, MQTT, etc.) ## Agent <-> Protocol relationship -Each agent type has a corresponding [Protocol](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/asset/agent/Protocol.java) implementation; the Agent stores the configuration which is then passed to an instance of the Agent's Protocol implementation so there is a one to one relationship. The following attributes are required for all agent types: +Each agent type has a corresponding [Protocol](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/asset/agent/Protocol.java) implementation; the Agent stores the configuration which is then passed to an instance of the Agent's Protocol implementation so there is a one-to-one relationship. The following attributes are required for all agent types: | Attribute | Description | Value type | | ------------- | ------------- | ------------- | @@ -34,13 +34,13 @@ Generic agents understand nothing about the underlying devices/service and ther | `messageStripDelimiter` | For protocols that use `messageDelimiters`, this indicates whether or not the matched delimiter should be stripped from the message. | Boolean | ## Agent links -Regular assets are connected to agents by adding an `Agent Link` configuration item to attributes that need connecting, agents can have their own `Agent Link` configuration options but below are the options that are common to all and can be found in the [Agent link](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/asset/agent/AgentLink.java) class; agents that don't have custom options use the `Default` Agent link type. +Regular assets are connected to agents by adding an `Agent Link` configuration item to attributes that need connecting, agents can have their own `Agent Link` configuration options but below are the options that are common to all and can be found in the [Agent link](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/asset/agent/AgentLink.java) class; agents that don't have custom options use the `Default` Agent link type. | Field | Description | Value type | Required | | ------------- | ------------- | ------------- | ------------- | | `id` | The agent ID that is the target for this agent link | [Asset ID](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/value/ValueType.java#L135) | Y | | `type` | Agent link type; must be the correct type for the agent/protocol being linked. Agent's that don't have a custom agent link type use the `type` value `Default` | Text | Y | -| `valueFilters` | When an agent protocol updates the value of a linked attribute it can be desirable to filter that value to extract a specific piece of information that should actually be written to the linked attribute; this option defines a series of value filters that incoming messages should pass through before being passed to the agent protocol, the incoming message is passed to each filter in array order and the result of one is the input to the next (i.e. they are composite). The available value filters can be found from the known types in the Javadoc but availabe types at the time of writing can be found below | [ValueFilter](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/value/ValueFilter.java) | N | +| `valueFilters` | When an agent protocol updates the value of a linked attribute it can be desirable to filter that value to extract a specific piece of information that should actually be written to the linked attribute; this option defines a series of value filters that incoming messages should pass through before being passed to the agent protocol, the incoming message is passed to each filter in array order and the result of one is the input to the next (i.e. they are composite). The available value filters can be found from the known types in the Javadoc but available types at the time of writing can be found below | [ValueFilter](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/value/ValueFilter.java) | N | | `valueConverter` | Defines a value converter map to allow for basic value type conversion; the incoming value will be converted to JSON and if this string matches a key in the converter then the value of that key will be pushed through to the attribute. An example use case is an API that returns `ACTIVE/DISABLED` text but you want to connect this to a Boolean attribute `true/false` | JSON Object | N | | `writeValueConverter` | Similar to `valueConverter` but for outbound (Attribute -> Agent protocol) messages | JSON Object | N | | `writeValue` | Text value to be used for outbound messages; can be used with any attribute type in combination with the dynamic placeholder (see below) or can be used with an attribute of type `ExecutionStatus` (i.e. executable attributes) to determine the value sent to the agent protocol when the attribute execution starts | Text (JSON etc.) | N | @@ -51,7 +51,7 @@ Regular assets are connected to agents by adding an `Agent Link` configuration i Dynamic injection of the written or current attribute value is supported in generic protocols by using the dynamic value placeholder `%VALUE[:FORMAT]%`, this can be used in the `writeValue` of the `AgentLink` as well as in other supported places depending on the protocol, for example the HTTP protocol supports using this in the headers, query parameters and/or path. The `:FORMAT` is optional and uses the [java.util.Formatter](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Formatter.html), if not specified then built in value conversion is used to convert the value into a JSON string representation. e.g. `%VALUE:%.2f%`, `%VALUE%` ### Dynamic Time Injection -Dynamic injection of the current time is supported in generic protocols by using the dynamic time placeholder `%TIME[+/-PnDTnHnMn.nS][:FORMAT]%`, this can be used in the `writeValue` of the `AgentLink` as well as in other supported places depending on the protocol, for example the HTTP protocol supports using this in the headers, query parameters and/or path. The `+/-PnDTnHnMn.nS` and `:FORMAT` are optional where `+/-PnDTnHnMn.nS` uses [java.time.Durtion.parse()](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)) and `:FORMAT` uses [DateTimeFormatter](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/time/format/DateTimeFormatter.html) with added support for `EPOCH_MILLIS` and `EPOCH_SECONDS` if `:FORMAT` is not specified then [ISO_INSTANT](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT) is asssumed. e.g. `%TIME%`, `%TIME-PT1H%`, `%TIME+P20D:yyyy-dd-mm%`, `%TIME:EPOCH_MILLIS%` +Dynamic injection of the current time is supported in generic protocols by using the dynamic time placeholder `%TIME[+/-PnDTnHnMn.nS][:FORMAT]%`, this can be used in the `writeValue` of the `AgentLink` as well as in other supported places depending on the protocol, for example the HTTP protocol supports using this in the headers, query parameters and/or path. The `+/-PnDTnHnMn.nS` and `:FORMAT` are optional where `+/-PnDTnHnMn.nS` uses [java.time.Duration.parse()](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)) and `:FORMAT` uses [DateTimeFormatter](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/time/format/DateTimeFormatter.html) with added support for `EPOCH_MILLIS` and `EPOCH_SECONDS` if `:FORMAT` is not specified then [ISO_INSTANT](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT) is assumed. e.g. `%TIME%`, `%TIME-PT1H%`, `%TIME+P20D:yyyy-dd-mm%`, `%TIME:EPOCH_MILLIS%` ### Value filter known types diff --git a/docs/user-guide/agents-protocols/partner-integrations.md b/docs/user-guide/agents-protocols/partner-integrations.md index 4861d89..dc443ec 100644 --- a/docs/user-guide/agents-protocols/partner-integrations.md +++ b/docs/user-guide/agents-protocols/partner-integrations.md @@ -15,7 +15,7 @@ As we are 100% open source we invite other companies to develop an integration. Documentation: - [Teltonika Wiki - Integrating with OpenRemote](https://wiki.teltonika-networks.com/view/OpenRemote?utm_source=partner&utm_medium=referral&utm_campaign=teltonika-networks-openremote-wiki) -- [OpenRemote Documentation - Manager APIs - MQTT Broker](../manager-apis/manager-apis.md#mqtt-api-mqtt-broker) +- [OpenRemote Documentation - Manager APIs - MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) ## Teltonika Vehicle Telematics ![TELTONIKA-Telematics](img/teltonika-telematics.png) diff --git a/docs/user-guide/agents-protocols/z-wave.md b/docs/user-guide/agents-protocols/z-wave.md index 8101e43..a0981e9 100644 --- a/docs/user-guide/agents-protocols/z-wave.md +++ b/docs/user-guide/agents-protocols/z-wave.md @@ -28,7 +28,7 @@ volumes: devices: - /dev/ttyACM0:/dev/ttyS0 ... -... +... ``` In this example the serial port `/dev/ttyACM0` of the host is mapped to the serial port `/dev/ttyS0` of the `manager` Docker container. @@ -61,41 +61,41 @@ You can repeat this procedure as often as you want and devices are not imported ## Include Z-Wave devices -This procedure describes how to add a new device to the Z-Wave network (Z-Wave device inclusion). +This procedure describes how to add a new device to the Z-Wave network (Z-Wave device inclusion). Note that before you are able to execute this procedure you have to execute the `Import Z-Wave Devices` procedure at least once otherwise the `Z-Wave Controller` asset is missing. 1. Select `Z-Wave Controller` in the asset list on the left side -2. Activate the `Device Inclusion` checkbox +2. Activate the `Device Inclusion` checkbox 3. Put the Z-Wave device into inclusion mode (see device manual) 4. Execute the `Import Z-Wave Devices` procedure in order to add the new device to the asset list on the left side ## Exclude Z-Wave devices -This procedure describes how to remove a device from the Z-Wave network (Z-Wave device exclusion). +This procedure describes how to remove a device from the Z-Wave network (Z-Wave device exclusion). Note that before you are able to execute this procedure you have to execute the `Import Z-Wave Devices` procedure at least once otherwise the `Z-Wave Controller` asset is missing. 1. Select `Z-Wave Controller` in the asset list on the left side -2. Activate the `Device Exclusion` checkbox +2. Activate the `Device Exclusion` checkbox 3. Put the Z-Wave device into exclusion mode (see device manual) ## Configure Z-Wave device parameters -1. Select the Z-Wave device in the asset list on the left side and and expand it so that you see the `Parameters` group +1. Select the Z-Wave device in the asset list on the left side and expand it so that you see the `Parameters` group 2. Expand the `Parameters` group -3. Select the Z-Wave parameter on the left side +3. Select the Z-Wave parameter on the left side 4. Edit the selected Z-Wave parameter on the right side. To get information about the selected Z-Wave parameter read the text in the `Description` attribute on the right side. The attribute with the disabled `Write` button shows the current Z-Wave parameter value. All other attributes with an enabled `Write` button are used to modify the Z-Wave parameter value. In case of a battery powered device you have to wakeup the device (see device manual) so that the configured parameter value can be sent to the device. ## Additional info -Unfortunately, `Docker for Windows` and `Docker for Mac` do not support device pass through. In case of a Windows or Mac computer you have to install Linux as a virtual machine by means of VirtualBox. There are two options to do this. +Unfortunately, `Docker for Windows` and `Docker for Mac` do not support device pass through. In case of a Windows or Mac computer you have to install Linux as a virtual machine by means of VirtualBox. There are two options to do this. -### Windows - Option 1 (Docker Toolbox) +### Windows - Option 1 (Docker Toolbox) 1. Download and install [VirtualBox](https://www.virtualbox.org/wiki/Downloads). 2. Download and install [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads) -3. On Windows 10 open the `Windows Features` window and make sure that the following features have **not** been selected: `Hyper-V`, `Virtual Machine Platform`, `Windows Subsystem for Linux`. +3. On Windows 10 open the `Windows Features` window and make sure that the following features have **not** been selected: `Hyper-V`, `Virtual Machine Platform`, `Windows Subsystem for Linux`. 4. Install [Docker Toolbox](https://docs.docker.com/toolbox). Select the following optional components: `Docker Compose for Windows` and `Git for Windows`. Do not select and install `VirtualBox`. 5. Start `Git Bash` and type the following command: ```shell @@ -104,7 +104,7 @@ docker-machine create --driver virtualbox --virtualbox-boot2docker-url https://g Note that if a virtual machine with the name `default` already exists you can delete it with the following command: ```shell docker-machine rm default -``` +``` 6. Start VirtualBox and select the virtual machine with the name `default` on the left side and go to Settings -> Network -> Adapter 1 -> Advanced -> Port Forwarding 7. Add the following rules: @@ -127,7 +127,7 @@ ls -al /dev/tty* | more ``` In case of a Aeotec Z-Stick Gen5 the USB device name is usually `/dev/ttyACM0`. The older Aeotec Z-Stick S2 has usually the name `/dev/ttyUSB0`. -### Mac - Option 1 (Docker Toolbox) +### Mac - Option 1 (Docker Toolbox) 1. Download and install [VirtualBox](https://www.virtualbox.org/wiki/Downloads). 2. Download and install [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads) @@ -139,7 +139,7 @@ docker-machine create --driver virtualbox --virtualbox-boot2docker-url https://g Note that if a virtual machine with the name `default` already exists you can delete it with the following command: ```shell docker-machine rm default -``` +``` 5. Start VirtualBox and select the virtual machine with the name `default` on the left side and go to Settings -> Network -> Adapter 1 -> Advanced -> Port Forwarding 6. Add the following rules: @@ -164,7 +164,7 @@ In case of a Aeotec Z-Stick Gen5 the USB device name is usually `/dev/ttyACM0`. ### Windows & Mac - Option 2 (Ubuntu VM) -1. Download and install [VirtualBox](https://www.virtualbox.org/wiki/Downloads) +1. Download and install [VirtualBox](https://www.virtualbox.org/wiki/Downloads) 2. Download and install [VirtualBox Extension Pack](https://www.virtualbox.org/wiki/Downloads) 3. Download [Ubuntu Desktop](https://ubuntu.com/download/desktop) 4. Start VirtualBox and create a new virtual machine by clicking the `New` button on the top toolbar. @@ -174,13 +174,13 @@ In case of a Aeotec Z-Stick Gen5 the USB device name is usually `/dev/ttyACM0`. * Memory size: Minimum `4096 MB` * Virtual hard disk size: Minimum `20 GB` 6. Click the `Start` button in the top toolbar and select the Ubuntu iso image that you've downloaded in step #3 in order to install Ubuntu -7. After installing Ubuntu it's recommended to install 'guest additions'. Start the Ubuntu virtual machine and in the upper menu bar select the following: Devices -> Insert Guest Additions CD image... +7. After installing Ubuntu it's recommended to install 'guest additions'. Start the Ubuntu virtual machine and in the upper menu bar select the following: Devices -> Insert Guest Additions CD image... 8. Install [Docker Engine](https://docs.docker.com/install/linux/docker-ce/ubuntu/) 9. Install [Docker Compose](https://docs.docker.com/compose/install/) 10. Shutdown the Ubuntu virtual machine and connect the Aeotec Z-Stick to the PC. In the VirtualBox Manager go to Settings -> Ports -> USB -> Port1 and add the following configuration: * Activate `Enable USB Controller` * Select `USB 3.0 (xHCI) Controller` - * Press the `Add Filter` button and select the Aeotec Z-Stick USB device (Sigma Designs, Inc.) + * Press the `Add Filter` button and select the Aeotec Z-Stick USB device (Sigma Designs, Inc.) 11. Find out the serial port name. Run the following command: ```shell dmesg -w @@ -192,11 +192,11 @@ You should see something like the following: In this example the resulting serial port name would be: ``` /dev/ttyACM0 -``` +``` ### Linux 1. Install [Docker Engine](https://docs.docker.com/engine/install/) -2. Install [Docker Compose](https://docs.docker.com/compose/install/) +2. Install [Docker Compose](https://docs.docker.com/compose/install/) 3. Find out the serial port name. Connect the Aeotec Z-Stick to the PC and execute the following command: ```shell dmesg -w diff --git a/docs/user-guide/anomaly-detection.md b/docs/user-guide/anomaly-detection.md index b6ac117..09ded21 100644 --- a/docs/user-guide/anomaly-detection.md +++ b/docs/user-guide/anomaly-detection.md @@ -10,7 +10,7 @@ unlisted: true ::: -OpenRemote includes the functionality to set up anomaly detection on all numeric attributes. This can be useful when you want to keep track of all the times a sensor sends an abnormal datapoint or if you want to be notified when such an datapoint is received. +OpenRemote includes the functionality to set up anomaly detection on all numeric attributes. This can be useful when you want to keep track of all the times a sensor sends an abnormal datapoint or if you want to be notified when such a datapoint is received. _Image of history chart with anomaly marked here_ @@ -18,11 +18,11 @@ _Image of history chart with anomaly marked here_ Currently there are 3 different types of detection methods you can use when configuring the anomaly detection on an attribute. All of these have their strengths and weaknesses based on the different types of data they receive. ## Range -This is the simples method to detect an outlier. To validate a datapoint it will look at a period of time before that datapoint, find the highest and lowest value and add an error margin on top of those values. These new minimum and maximum values will be the limit in which an point will be valid and any value outside these boundaries will be marked as an anomaly. The error margin and period of time the detection method uses can both be changed when configuring the method. +This is the simples method to detect an outlier. To validate a datapoint it will look at a period of time before that datapoint, find the highest and lowest value and add an error margin on top of those values. These new minimum and maximum values will be the limit in which a point will be valid and any value outside these boundaries will be marked as an anomaly. The error margin and period of time the detection method uses can both be changed when configuring the method. ![image](img/anomaly-range.png) _Visualization of the limits generated by the Range method_ -The advantage of this method is that it's easy to understand but can still detect the larger outliers. However it falls short when detecting a big increase during a time where the data is already far below the maximum value. +The advantage of this method is that it's easy to understand but can still detect the larger outliers. However it falls short when detecting a big increase during a time when the data is already far below the maximum value. ## Change @@ -30,7 +30,7 @@ The change method works in a similar way to the Range method. It also looks at a ![image](img/anomaly-change.png) _Visualization of the limits generated by the Change method_ -This method will follow the data more closely as seen in the visualization above but needs more careful configuration to ensure it wont detect to to many false anomalies. +This method will follow the data more closely as seen in the visualization above but needs more careful configuration to ensure it won't detect too many false anomalies. ## Forecast If the attribute you are configuring already has predicted datapoints, this will be the easiest method to set up. When new data is received it is compared to predicted datapoints from that time and if the difference is larger as a limit you can configure yourself it will be marked as an anomaly. diff --git a/docs/user-guide/assets-and-attributes/assets-agents-and-attributes.md b/docs/user-guide/assets-agents-and-attributes.md similarity index 68% rename from docs/user-guide/assets-and-attributes/assets-agents-and-attributes.md rename to docs/user-guide/assets-agents-and-attributes.md index 09629a4..58e0928 100644 --- a/docs/user-guide/assets-and-attributes/assets-agents-and-attributes.md +++ b/docs/user-guide/assets-agents-and-attributes.md @@ -1,36 +1,36 @@ --- -sidebar_position: 1 +sidebar_position: 3 --- # Assets, Agents and Attributes ## Assets -An asset is a digital representation of a physical or logical `Thing` (this is the `Thing` in Internet of Things). An asset is always attached to a realm, so data is not shared between realms so each realm is considered to be a silo. Assets are persisted. `OpenRemote` stores your current asset status in its database, and manages it in rules and flows. This collectively is called the context of your `OpenRemote` system. +An asset is a digital representation of a physical or logical `Thing` (this is the `Thing` in Internet of Things). An asset is always attached to a realm, so data is not shared between realms so each realm is considered to be a silo. Assets are persisted. OpenRemote stores your current asset status in its database, and manages it in rules and flows. This collectively is called the context of your OpenRemote system. ## Attributes -Each asset can have one or more attributes that hold a value; a value can be of any type that can be represented as `JSON`. The name of the attribute is used to cross reference it with an attribute descriptor (see below), which provides schema information for the attribute. +Each asset can have one or more attributes that hold a value; a value can be of any type that can be represented as JSON. The name of the attribute is used to cross-reference it with an attribute descriptor (see below), which provides schema information for the attribute. ## Configuration items -As well as having a value an attribute can have configuration items (called 'meta items' in the code) which control the behaviour of the attribute (link it to an agent for read/write from/to external systems, link to another attribute, configure historical value storage, and much more). Each attribute can have one or more meta items which is essentially a well known named value (meta data) that can be used in various parts of the system to control behaviour of the associated attribute (e.g. an `agentLink` meta item is used to connect an attribute to an agent/protocol). +As well as having a value an attribute can have configuration items (called 'meta items' in the code) which control the behaviour of the attribute (link it to an agent for read/write from/to external systems, link to another attribute, configure historical value storage, and much more). Each attribute can have one or more meta items which is essentially a well known named value (metadata) that can be used in various parts of the system to control behaviour of the associated attribute (e.g. an `agentLink` meta item is used to connect an attribute to an agent/protocol). ## Agents -Agents are a special type of asset which link external services/devices with your `OpenRemote` system via protocols (HTTP/TCP/IP/...). The agent itself holds the configuration parameters as attributes and this configuration is passed to an instance of the corresponding protocol; there is a one to one relationship between an agent and a protocol instance. [Read more about agents](../agents-protocols/overview.md) +Agents are a special type of asset which link external services/devices with your OpenRemote system via protocols (HTTP/TCP/IP/...). The agent itself holds the configuration parameters as attributes and this configuration is passed to an instance of the corresponding protocol; there is a one-to-one relationship between an agent and a protocol instance. [Read more about agents](agents-protocols/overview.md) ## Asset tree Assets can be structured in a hierarchical tree to define some logical hierarchy for a particular use case (e.g. A city has buildings, which has floors, which have presence sensors). ## Asset Type Model -Our asset type model is configurable which allows it to be modelled on the domain objects relevant for the specific use case (energy domain, smart city, etc.). At present it is only possible to configure the asset model in `java` code with the long term aim of allowing configuration via the `Manager UI`. You can [find the default asset type models here](https://github.com/openremote/openremote/tree/master/model/src/main/java/org/openremote/model/asset/impl) and use them as examples to create your own. +Our asset type model is configurable which allows it to be modelled on the domain objects relevant for the specific use case (energy domain, smart city, etc.). At present it is only possible to configure the asset model in Java code with the long term aim of allowing configuration via the `Manager UI`. You can [find the default asset type models here](https://github.com/openremote/openremote/tree/master/model/src/main/java/org/openremote/model/asset/impl) and use them as examples to create your own. -The asset model available for a given `OpenRemote` instance can be interrogated using the [Asset Model HTTP API](https://demo.openremote.io/swagger/#/Asset%20Model). +The asset model available for a given OpenRemote instance can be interrogated using the [Asset Model HTTP API](https://demo.openremote.io/swagger/#/Asset%20Model). The asset model has the following types and structure: * Asset type info - * Asset descriptor (unique within a given `OpenRemote` instance) + * Asset descriptor (unique within a given OpenRemote instance) * Attribute descriptor(s) - List of attribute descriptors applicable to this asset type, a given attribute name is unique within a given asset type hierarchy - * Meta Item descriptor names(s) - List of meta item descriptor names applicable to this asset type, each one is unique within a given `OpenRemote` instance and can be used to lookup the actual meta item Descriptor - * Value descriptor name(s) - List of value descriptor names applicable to this asset type, each one is unique within a given `OpenRemote` instance and can be used to lookup the actual value descriptor + * Meta Item descriptor names(s) - List of meta item descriptor names applicable to this asset type, each one is unique within a given OpenRemote instance and can be used to look up the actual meta item Descriptor + * Value descriptor name(s) - List of value descriptor names applicable to this asset type, each one is unique within a given OpenRemote instance and can be used to look up the actual value descriptor ### Asset type info Asset type info contains all the descriptors applicable for a given asset type and can be considered the schema definition which is then used for validation and UI generation purposes; the basic asset type is `Thing` which has no attribute constraints but can be used as a generic asset. @@ -39,7 +39,7 @@ The options depend on the asset types loaded into your deployment. You can call ### Asset descriptor An asset descriptor defines the following information for a specific asset type: -* `name` - this must be unique within a given `OpenRemote` instance and should be the simple `java` class name +* `name` - this must be unique within a given OpenRemote instance and should be the simple Java class name * `icon` - an optional icon that can be used by frontend UI to represent asset's of this type on maps etc. * `colour` - an optional colour that can be used by frontend UI to represent asset's of this type on maps etc. @@ -54,18 +54,18 @@ An attribute descriptor has a name which refers to the name of the attribute and * `optional` - boolean flag indicating if the attribute must be present (this doesn't control whether or not it must have a value - that is handled by constraints) ### Meta items descriptor -A meta item descriptor has a name which refers to the name of the meta item and this must be unique within the `OpenRemote` instance, it also contains the following information: +A meta item descriptor has a name which refers to the name of the meta item and this must be unique within the OpenRemote instance, it also contains the following information: * `type` - same as attribute descriptor above * `constraints` - same as attribute descriptor above * `format` - same as attribute descriptor above * `units` - same as attribute descriptor above -For details on the built in meta item descriptors available see [here](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/value/MetaItemType.java), +For details on the built-in meta item descriptors available see [here](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/value/MetaItemType.java), for asset/agent specific configuration items check their documentation pages and/or Javadoc. ### Value descriptors -A value descriptor has a name which must be unique within the `OpenRemote` instance, it ultimately describes the shape of the data for serialisation/deserialisation purposes and it also contains the following information: +A value descriptor has a name which must be unique within the OpenRemote instance, it ultimately describes the shape of the data for serialisation/deserialisation purposes and it also contains the following information: * `type` - the simple class name of the data type this value descriptor describes * `jsonType` - the `JSON` type of data type @@ -74,4 +74,4 @@ A value descriptor has a name which must be unique within the `OpenRemote` insta * `format` - same as attribute descriptor above * `units` - same as attribute descriptor above -For details on the built in value descriptors available see [here](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/value/ValueType.java). +For details on the built-in value descriptors available see [here](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/value/ValueType.java). diff --git a/docs/user-guide/assets-and-attributes/_category_.json b/docs/user-guide/assets-and-attributes/_category_.json deleted file mode 100644 index 26f6417..0000000 --- a/docs/user-guide/assets-and-attributes/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Assets and Attributes", - "position": 3, - "link": { - "type": "generated-index" - } -} diff --git a/docs/user-guide/deploying/aws-cloudformation.md b/docs/user-guide/deploying/aws-cloudformation.md index 75f60ca..78da16e 100644 --- a/docs/user-guide/deploying/aws-cloudformation.md +++ b/docs/user-guide/deploying/aws-cloudformation.md @@ -6,7 +6,7 @@ sidebar_position: 3 The CloudFormation template can be found at [cloudformation-create-vpc.yml](https://github.com/openremote/openremote/blob/master/.ci_cd/aws/cloudformation-create-vpc.yml). -At OpenRemote we use AWS for hosting our deployments, this guide explains how to create and configure AWS EC2 hosts using CloudFormation for running the OpenRemote started with Docker Compose; it is written from the OpenRemote organisation perspective but can be used to assist in setting up your own AWS hosted infrastructure. Please refer to the AWS documentation for more details on the services/tools mentioned (we don't generally offer AWS support but some kind person may be able to help on the [forum](https://forum.openremote.io). +At OpenRemote we use AWS for hosting our deployments, this guide explains how to create and configure AWS EC2 hosts using CloudFormation for running the OpenRemote started with Docker Compose; it is written from the OpenRemote organisation perspective but can be used to assist in setting up your own AWS hosted infrastructure. Please refer to the AWS documentation for more details on the services/tools mentioned (we don't generally offer AWS support but some kind person may be able to help on the [forum](https://forum.openremote.io)). ## AWS services/tools used To manage the OpenRemote deployments we use the following AWS services/tools: @@ -27,7 +27,7 @@ For interactive (UI login) it is recommended to use the [single sign on portal]( For CLI login then an AWS access key ID and secret is needed. ## AWS Region -AWS resources are siloed into datacentre regions; this guide focuses on a single region setup specifically `eu-west-1`; in the UI the region can be selected in the top right. +AWS resources are siloed into datacenter regions; this guide focuses on a single region setup specifically `eu-west-1`; in the UI the region can be selected in the top right. ## Pre-requisites diff --git a/docs/user-guide/deploying/balena-deployment.md b/docs/user-guide/deploying/balena-deployment.md index 668a70b..77a98e1 100644 --- a/docs/user-guide/deploying/balena-deployment.md +++ b/docs/user-guide/deploying/balena-deployment.md @@ -12,7 +12,7 @@ Balena is the totality of the product. Look at [balena.io](https://balena.io). * BalenaOS is the Operating System which runs on edge devices (Raspberry Pis, Intel NUCs, etc.). BalenaOS is able to run Docker containers (with a limited feature-set), and allows management by OpenBalena/BalenaCloud. * OpenBalena is the open-source backend software that can manage fleets (groups) of devices. It can push new versions of - images to devices, manage those devices (power management, resource management, environment variables, etc) + images to devices, manage those devices (power management, resource management, environment variables, etc.) * BalenaCloud is (the company) Balena's SaaS product, which uses OpenBalena for their core part of the backend, like the device API, the image registry, etc. BalenaCloud uses part of openBalena for its backend services. diff --git a/docs/user-guide/deploying/configuring-the-manager-ui.md b/docs/user-guide/deploying/configuring-the-manager-ui.md index 0876697..50f599e 100644 --- a/docs/user-guide/deploying/configuring-the-manager-ui.md +++ b/docs/user-guide/deploying/configuring-the-manager-ui.md @@ -10,7 +10,7 @@ In this user guide we will use an example JSON manager_config and give a short d :::note -If you are logged in as the default 'admin' user (a super user) most of these styling changes will _not_ be shown. This is to make sure the 'admin' user has all functionality available to them. +If you are logged in as the default 'admin' user (a superuser) most of these styling changes will _not_ be shown. This is to make sure the 'admin' user has all functionality available to them. ::: @@ -462,7 +462,7 @@ Set which assettypes are excluded from the list of asset types that can be selec } } ``` -**Realm configuration:** You can set the branding per realm. In the example below you can see how the page title, headers, colors, and logo's are set as default (for any new realm created through the UI), as well as for the 'master' and 'clienta' realms. +**Realm configuration:** You can set the branding per realm. In the example below you can see how the page title, headers, colors, and logos are set as default (for any new realm created through the UI), as well as for the 'master' and 'clienta' realms. ```json "realms": { "default": { diff --git a/docs/user-guide/domains/create-your-energy-management-system.md b/docs/user-guide/domains/create-your-energy-management-system.md index f10ea9c..93b407c 100644 --- a/docs/user-guide/domains/create-your-energy-management-system.md +++ b/docs/user-guide/domains/create-your-energy-management-system.md @@ -82,7 +82,7 @@ To be able to forecast the wind power, you have to fill in the following attribu * Wind speed max (also called cut-off speed, the maximum speed at which a turbine is normally operating; above it will be turned down; in m/s) * Wind speed min (also called cut-in speed, the minimum speed required to operate the wind turbine; in m/s) * Wind speed reference (also called nominal or rated speed; in m/s) -* Location. You can do this in the 'MODIFY' mode by opening the map modal next to the location attribute and setting the location by double clicking on the map. +* Location. You can do this in the 'MODIFY' mode by opening the map modal next to the location attribute and setting the location by double-clicking on the map. Now can turn on the attribute 'Include forecast wind service' on your wind turbine asset (see Figure 3). Once saved the forecast service is running. To see it in action you can go to the 'Insights' page and select the power attribute in a chart. The dotted line will represent the forecasted data. @@ -110,7 +110,7 @@ Turn on the attributes 'Supports import' and 'Supports' export. This is an indic If you don't have a battery but want to simulate it and see what you can achieve in terms of financial or carbon savings, you can use the 'Storage Simulator Agent'. In this tutorial we use that option. -Add the 'Storage Simulator Agent' first. Than add the configuration item 'Agent link' and link to the 'Storage Simulator Agent', for six attributes: +Add the 'Storage Simulator Agent' first. Then add the configuration item 'Agent link' and link to the 'Storage Simulator Agent', for six attributes: * Energy level * Energy level percentage * Power @@ -140,8 +140,8 @@ There is a series of attributes on the vehicle you need or can use the make the * Power import max, required to set the maximum charge power the vehicle can handle * Power export max, required to set the maximum discharge power the vehicle can handle * Energy level schedule. This sets the hour of the day, for each day of the week, at which the battery needs to be charged at the indicated percentage (see figure 6). It is not required but prevents an empty battery while you need your car to drive somewhere! -* Energy level percentage max. The optimisation will never charge beyond. Without setting it it will assume 100% -* Energy level percentage min. If a vehicle get's connected with a lower level, it will immediately start charging until it reaches the minimum level. If not set it will assume 0%. +* Energy level percentage max. The optimisation will never charge beyond. Without setting it, it will assume 100% +* Energy level percentage min. If a vehicle gets connected with a lower level, it will immediately start charging until it reaches the minimum level. If not set it will assume 0%. In some cases you also want to connect to your charger, and make the vehicle a child of the charger, e.g.: * In case you can't control the power setpoint on your vehicle. You will need to link the 'Power setpoint' of your charger to your charging system, using any of the existing [Agent Protocol options](../agents-protocols/overview.md). In addition you can use the 'Flow editor' to link the 'Power setpoint' of your vehicle to the 'Power setpoint' of your charger. The optimisation will now set the 'Power setpoint' of your vehicle, which will then be forwarded to the 'Power setpoint' of your charger. diff --git a/docs/user-guide/gateways-and-devices/auto-provisioning.md b/docs/user-guide/gateways-and-devices/auto-provisioning.md index ec47197..17b5952 100644 --- a/docs/user-guide/gateways-and-devices/auto-provisioning.md +++ b/docs/user-guide/gateways-and-devices/auto-provisioning.md @@ -41,11 +41,11 @@ Jump to: ## Implementation ### Connect flow -The following illustrates the connect process (through [MQTT topics](../manager-apis/manager-apis.md#mqtt-api-mqtt-broker)) which clients can use to auto provision a service user and optionally an asset whose ID is generated using a UNIQUE_ID provided by the client; the client is then authenticated and the asset is then returned to the client. +The following illustrates the connect process (through [MQTT topics](../manager-apis.md#mqtt-api-mqtt-broker)) which clients can use to auto provision a service user and optionally an asset whose ID is generated using a UNIQUE_ID provided by the client; the client is then authenticated and the asset is then returned to the client. ![Auto provisioning Connect flow](img/auto-provisioning-connect-flow.png) -**NOTE THAT THE 'WHITELIST/BLACKLIST FAILURE', IS NOT YET IMPLEMENTED. THIS FUNCTION ENHANCES SECURITY AS ONLY SPECIFIED DEVICES CAN CONNECT (WHITELIST) OR CAN BE EXLUCDED (BLACKLIST)** +**NOTE THAT THE 'WHITELIST/BLACKLIST FAILURE', IS NOT YET IMPLEMENTED. THIS FUNCTION ENHANCES SECURITY AS ONLY SPECIFIED DEVICES CAN CONNECT (WHITELIST) OR CAN BE EXCLUDED (BLACKLIST)** #### X.509 Client Certificate Validation @@ -126,10 +126,10 @@ The code field should be the base64 encoded HMAC specific to this client. Client certificate generation is done using standard tooling e.g. openssl: 1. A unique client private key and X.509 certificate should be generated with the client’s unique ID stored in the CN attribute of the certificate. -1. The certificate should then be signed by an intermediate CA (can be self signed or signed by a CA) +1. The certificate should then be signed by an intermediate CA (can be self-signed or signed by a CA) 1. The intermediate CA certificate is then uploaded into OpenRemote within a Realm config instance -When the client publishes its’ certificate to OpenRemote it must be in the PEM format. Client certificate generation can take place within the manufacturing environment without any external dependencies. +When the client publishes its certificate to OpenRemote it must be in the PEM format. Client certificate generation can take place within the manufacturing environment without any external dependencies. :::note @@ -139,7 +139,7 @@ The security of the CA private key(s) is essential, if compromised then the cert ##### Some useful commands: -Generate self signed CA cert (inc. key): +Generate self-signed CA cert (inc. key): ```shell openssl req -x509 -sha256 -nodes -newkey rsa:4096 -keyout ca.key -days 730 -out ca.pem ``` @@ -164,7 +164,7 @@ The type of the asset generated must be an asset type that exists in the system; ## Configuration -Configuration of auto provisioning is done via the `Manager UI` -> Auto Provisioning (top right menu); the menu item is only present for super users. +Configuration of auto provisioning is done via the `Manager UI` -> Auto Provisioning (top right menu); the menu item is only present for superusers. ### Provisioning Configuration @@ -251,11 +251,11 @@ awk 'NF {sub(/\r/, ""); printf "%s\n",$0;}' ## Obtaining an asset template 1. Log into the `Manager UI` and navigate to the asset viewer 1. Create then select an asset of the same type that you want to use in the template then select the asset ID from the address bar (e.g. `https://staging.demo.openremote.io/manager/?realm=smartcity#/assets/false/2K3nSg148fnzlSlaem0kkh` -> `2K3nSg148fnzlSlaem0kkh`) -1. Navigate to swagger UI (https://your_installation/swagger e.g. https://staging.demo.openremote.io/swagger) +1. Navigate to Swagger UI (https://your_installation/swagger e.g. https://staging.demo.openremote.io/swagger) 1. Click authorize then again on the popup dialog then login with a user from the master realm 1. Once authenticated go to `Assets -> Get /asset/{assetId}` and paste the asset ID into the asset ID input then execute the query, you will then get the asset returned in `json` format: ![image](img/get-asset-request.png) 1. You can copy the returned `json` and paste that into the `Asset template` input field: - 1. Remove or set the the `parentId` to determine where in the asset tree the asset will be created + 1. Remove or set the `parentId` to determine where in the asset tree the asset will be created 1. remember to insert the `%UNIQUE_ID%` placeholder wherever you would like that to be used (in an attribute value, in the asset name, etc.) diff --git a/docs/user-guide/gateways-and-devices/connect-esp32-or-esp8266-using-mqtt.md b/docs/user-guide/gateways-and-devices/connect-esp32-or-esp8266-using-mqtt.md index f223414..759def0 100644 --- a/docs/user-guide/gateways-and-devices/connect-esp32-or-esp8266-using-mqtt.md +++ b/docs/user-guide/gateways-and-devices/connect-esp32-or-esp8266-using-mqtt.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Connect ESP32 or ESP8266 using MQTT -ESP32 and ESP8266 are some of the most popular and well established boards for devices by Espressif. ESP32 and ESP8266 (and other types) can be easily linked to an OpenRemote instance using our MQTT Broker. If you have larger numbers of devices connecting you might want to use the auto provisioning flow. This allows you to provision your devices in such a way that they automatically connect your devices to OpenRemote, create an asset of the type you have defined, and link the attributes over the right topics. ESP32 and and ESP8266 are perfectly suitable to make use of it. +ESP32 and ESP8266 are some of the most popular and well established boards for devices by Espressif. ESP32 and ESP8266 (and other types) can be easily linked to an OpenRemote instance using our MQTT Broker. If you have larger numbers of devices connecting you might want to use the auto provisioning flow. This allows you to provision your devices in such a way that they automatically connect your devices to OpenRemote, create an asset of the type you have defined, and link the attributes over the right topics. ESP32 and ESP8266 are perfectly suitable to make use of it. Here are some practical tips and code samples to get you going. @@ -90,7 +90,7 @@ void reconnect() { -This Code is for an ESP32. In case you use an ESP8266, change the WiFi Library. #include <ESP8266WiFi.h> (see code) +This Code is for an ESP32. In case you use an ESP8266, change the Wi-Fi Library. #include <ESP8266WiFi.h> (see code) For ESP8266 SSL Connection, you need a fingerprint of your Server Certificate Example: `"static const char *fingerprint PROGMEM = "00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00";"` @@ -172,5 +172,5 @@ Note you need to add a CA certificate and add the code to locate the appropriate ## See Also - [Tutorial: Connect your MQTT Client](../../tutorials/connect-your-mqtt-client.md) -- [User Guide: Manager APIs](../manager-apis/manager-apis.md) +- [User Guide: Manager APIs](../manager-apis.md) - [User Guide: Auto Provisioning](../gateways-and-devices/auto-provisioning.md) diff --git a/docs/user-guide/gateways-and-devices/edge-gateway.md b/docs/user-guide/gateways-and-devices/edge-gateway.md index debc4ff..540f750 100644 --- a/docs/user-guide/gateways-and-devices/edge-gateway.md +++ b/docs/user-guide/gateways-and-devices/edge-gateway.md @@ -26,7 +26,7 @@ Just create a new Asset of type Gateway and the manager will provision a Keycloa ![](img/manager-gateway-asset.png) ### 2. Entering credentials in the edge gateway - 1. On the edge gateway login to the manager UI and select the realm you wish to connect to the central manager (only applicable to super users). + 1. On the edge gateway login to the manager UI and select the realm you wish to connect to the central manager (only applicable to superusers). 1. Go to the Manager interconnect page (top right menu) 1. Enter the host (e.g. `demo.openremote.io`) 1. Enter port if not using default `80` or `443` @@ -44,7 +44,7 @@ Just create a new Asset of type Gateway and the manager will provision a Keycloa ## Interaction with Gateway Manager UI via Gateway tunnels -On top of the Interaction via the Gateway, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. Note that you first have to [technically configure the (edge) gateway and central instance of OpenRemote to enable the the tunnelling set-up](../../developer-guide/gateway-tunnelling-setup.md). Next you can acces the Manager UI of the Gateway instance via the 'Gateway Tunnels' (Settings) or via a 'Gateway Widget' on the Insights dashboards. +On top of the Interaction via the Gateway, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. Note that you first have to [technically configure the (edge) gateway and central instance of OpenRemote to enable the tunnelling set-up](../../developer-guide/gateway-tunnelling-setup.md). Next you can access the Manager UI of the Gateway instance via the 'Gateway Tunnels' (Settings) or via a 'Gateway Widget' on the Insights dashboards. ![](img/create-gateway-tunnel.png) _Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ @@ -56,4 +56,4 @@ _Creating a gateway tunnel and opening the manager UI of the remote instance whi ### Edge Gateway - Processor: AMD64 or ARM64 - RAM: 4GB (if using Keycloak identity provider) 2GB (if using basic identity provider) -- Disk: 1.5GB (preferrably SATA or eMMC) +- Disk: 1.5GB (preferably SATA or eMMC) diff --git a/docs/user-guide/identity-and-security/realms-users-and-roles.md b/docs/user-guide/identity-and-security/realms-users-and-roles.md index 5ae0ee4..a1a545c 100644 --- a/docs/user-guide/identity-and-security/realms-users-and-roles.md +++ b/docs/user-guide/identity-and-security/realms-users-and-roles.md @@ -4,10 +4,10 @@ sidebar_position: 1 # Realms, users and roles -Authentication and Authorization in the OpenRemote stack is powered by the [Keycloak](https://www.keycloak.org/) `OpenID Connect Provider` and utilises `OAuth 2.0`. Generally within in an instance of the `OpenRemote` stack the `Keycloak` server is accessible at: `/auth` but should only be used by advanced users that know what they're doing as **you can completely break your instance**. +Authentication and Authorization in the OpenRemote stack is powered by the [Keycloak](https://www.keycloak.org/) `OpenID Connect Provider` and utilises `OAuth 2.0`. Generally within in an instance of the OpenRemote stack the Keycloak server is accessible at: `/auth` but should only be used by advanced users that know what they're doing as **you can completely break your instance**. ## Realms -Realms (also known as Tenants) in OpenRemote provide a layer of isolation with each realm having their own users, assets, rules and even UI styling. This allows for multi-tenancy use cases and realms can only be managed by super users. A realm user can only see and access their own realm and resources within this realm, super users are able to access all realms. Individual Realms can be reached at `https://youradress/manager/?realm=realmname`. For more details, see [Realms](../manager-ui/#realms). +Realms (also known as Tenants) in OpenRemote provide a layer of isolation with each realm having their own users, assets, rules and even UI styling. This allows for multi-tenancy use cases and realms can only be managed by superusers. A realm user can only see and access their own realm and resources within this realm, super users are able to access all realms. Individual Realms can be reached at `https://youradress/manager/?realm=realmname`. For more details, see [Realms](../manager-ui/#realms). ## Users There are two basic types of user within OpenRemote, all can be managed within the Manager UI or programmatically via custom setup code: @@ -16,10 +16,10 @@ There are two basic types of user within OpenRemote, all can be managed within t These are users that login interactively by filling in their username and password on the login page, in OAuth 2.0 terminology this is the `authorizationCode` grant type. ### Service users -These are users that login programmatically using a client ID and secret and is designed for confidential clients to connect to the `Manager APIs` (i.e. `MQTT`, `WebSockets` and/or `HTTP`) without user interaction, in OAuth 2.0 terminology this is the `client_credentials` grant type. +These are users that login programmatically using a client ID and secret and is designed for confidential clients to connect to the [Manager APIs](../manager-apis.md) (i.e. MQTT, WebSockets and/or HTTP) without user interaction, in OAuth 2.0 terminology this is the `client_credentials` grant type. ## Roles -Roles (technically composite roles or role groups) can be defined by selecting the various 'read' and 'write' access rights for the various functions of the system. Each realm has it's own set of roles and a user can be assigned zero or more of these roles within their realm and they are composite as they combine together to form the overall authorization/permissions for a user. Roles used by OpenRemote are defined in [ClientRole](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/security/ClientRole.java). +Roles (technically composite roles or role groups) can be defined by selecting the various 'read' and 'write' access rights for the various functions of the system. Each realm has its own set of roles and a user can be assigned zero or more of these roles within their realm and they are composite as they combine to form the overall authorization/permissions for a user. Roles used by OpenRemote are defined in [ClientRole](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/security/ClientRole.java). ## Realm roles There are two additional realm roles for users within OpenRemote. @@ -30,4 +30,4 @@ User set with realm role 'Restricted user' and are linked to one or mores assets ### Super admin realm role -Within the system we have the concept of super users, these are users in the master realm with the `Super admin` realm role, they have the ability to create and manage realms and everything within any realm. Note that you should additionally give them all 'read/write' roles. +Within the system we have the concept of superusers, these are users in the master realm with the `Super admin` realm role, they have the ability to create and manage realms and everything within any realm. Note that you should additionally give them all 'read/write' roles. diff --git a/docs/user-guide/manager-apis/manager-apis.md b/docs/user-guide/manager-apis.md similarity index 92% rename from docs/user-guide/manager-apis/manager-apis.md rename to docs/user-guide/manager-apis.md index feae95f..91a72bf 100644 --- a/docs/user-guide/manager-apis/manager-apis.md +++ b/docs/user-guide/manager-apis.md @@ -1,10 +1,10 @@ --- -sidebar_position: 1 +sidebar_position: 5 --- # Manager APIs -The OpenRemote Manager API is composed of the following APIs, each API requires authentication (with the exception of `read`/`write` of public `asset` `attributes` see [Asset security](../identity-and-security/asset-security.md)). +The OpenRemote Manager API is composed of the following APIs, each API requires authentication (with the exception of `read`/`write` of public `asset` `attributes` see [Asset security](identity-and-security/asset-security.md)). To be able to authenticate you'll need to create a service user using the Manager UI (must be logged in as super user to access this functionality), please refer to the Manager UI user guide; access tokens can be obtained from the token endpoint using standard OAuth 2.0 techniques. @@ -13,7 +13,11 @@ To be able to authenticate you'll need to create a service user using the Manage * Service user supported grant type(s): `client_credentials` ## HTTP API -This is the traditional request response API with live documentation available via Swagger UI (see `/swagger/` URL of your manager) or you can look at the [demo environment](https://demo.openremote.io/swagger/). Authentication is done using standard `Authorization` header bearer token where the token is a valid access token obtained from the OAuth 2.0 token endpoint. +This is the traditional request response API which is documented in the [REST API](/docs/category/rest-api) chapter. + +Live documentation is also available via Swagger UI (see `/swagger/` URL of your manager) or you can look at the [demo environment Swagger UI](https://demo.openremote.io/swagger/). + +Authentication is done using standard `Authorization` header bearer token where the token is a valid access token obtained from the OAuth 2.0 token endpoint. * Base URL: `/api/{realm}/` * Authorization Header: `Authorization: Bearer {accessToken}` @@ -82,7 +86,7 @@ Examples: :::note -`attributevalue` topic prefix can be used in place of `attribute` to only return the value of the [AttributeEvent](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/attribute/AttributeEvent.java) rather then the entire event.** +`attributevalue` topic prefix can be used in place of `attribute` to only return the value of the [AttributeEvent](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/attribute/AttributeEvent.java) rather than the entire event.** ::: diff --git a/docs/user-guide/manager-apis/_category_.json b/docs/user-guide/manager-apis/_category_.json deleted file mode 100644 index ac160fa..0000000 --- a/docs/user-guide/manager-apis/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Manager APIs", - "position": 5, - "link": { - "type": "generated-index" - } -} diff --git a/docs/user-guide/manager-ui/manager-ui.md b/docs/user-guide/manager-ui/manager-ui.md index 876650b..5fb4f5e 100644 --- a/docs/user-guide/manager-ui/manager-ui.md +++ b/docs/user-guide/manager-ui/manager-ui.md @@ -12,7 +12,7 @@ If you open the application you will get four main pages: [Map](#map), [Assets]( ## Map -The `Map` page will show your map (see the [custom deployment](../deploying/custom-deployment.md) documentation if you like to change the map). You can pan, zoom, and tilt the map. On the map all assets are shown which have a location as well the configuration item `show on dashboard` set. Assets can both have static or dynamic locations (eg. a car, boat or plane). You will see the direction an asset is facing or moving if the asset includes an attribute called 'direction'. When selecting an asset, a panel will show its attributes and values. The `Asset details` button in this panel will bring you to the respective Asset page. +The `Map` page will show your map (see the [custom deployment](../deploying/custom-deployment.md) documentation if you like to change the map). You can pan, zoom, and tilt the map. On the map all assets are shown which have a location as well the configuration item `show on dashboard` set. Assets can both have static or dynamic locations (e.g. a car, boat or plane). You will see the direction an asset is facing or moving if the asset includes an attribute called 'direction'. When selecting an asset, a panel will show its attributes and values. The `Asset details` button in this panel will bring you to the respective Asset page. As part of the [configuring the manager UI](../deploying/configuring-the-manager-ui.md) you can also configure assets to change their colour based on an attribute value (number, boolean, or string) and show a label with or without units. @@ -69,22 +69,22 @@ While in `Edit asset` mode you can expand each attribute, which gives you the op | `Read only` | Data can not be filled via UI, only by agents or rules | | `Rule event` | Events are stored in rule to allow evaluation of change history of an attribute | | `Rule event expires` | Set lifetime of event triggers and facts | -| `Rule state` | Add this attribute as option to select in rules, on lefthand side | +| `Rule state` | Add this attribute as option to select in rules, on left-hand side | | `Rule reset immediate` | Allows rule to re-trigger immediately. Can be useful for event based data | | `Secret` | Marks the value as secret indicating clients to display this in a concealed manner | | `Show on dashboard` | Used in combination with 'location' will display asset on the Map view | | `Store data points` | Stores data points in the database, default for one month | -| `Units` | Adds a unit to the attribute value, see [composition and options](../assets-and-attributes/assets-agents-and-attributes.md#attribute-descriptor) | +| `Units` | Adds a unit to the attribute value, see [composition and options](../assets-agents-and-attributes.md#attribute-descriptor) | | `User connected` | Shows all restricted users which have access to this asset, [see](../identity-and-security/realms-users-and-roles.md#restricted-user-realm-role) | -See the documentation page [explaining all available configuration item options for assets and attributes, and references](../assets-and-attributes/assets-agents-and-attributes.md#asset-type-model). Don't forget to save the asset after making changes. +See the documentation page [explaining all available configuration item options for assets and attributes, and references](../assets-agents-and-attributes.md#asset-type-model). Don't forget to save the asset after making changes. ### Create an agent -Agents are a specific type of asset used to connect to external sensors, actuators, gateways, or services using protocols. They are added in the same manner as assets by clicking the `+` in the header of the asset tree. This will open a modal that shows the available agent types at the top of the list. You will see the generic ones: [HTTP](../agents-protocols/http.md), [WebSocket](../agents-protocols/websocket-agent.md), [MQTT](../agents-protocols/mqtt.md), [TCP](../agents-protocols/tcp.md), [UDP](../agents-protocols/udp.md) and [SNMP](../agents-protocols/snmp.md); as well as more specific ones like [Z-wave](../agents-protocols/z-wave), [KNX](../agents-protocols/knx) or [Velbus](../agents-protocols/velbus.md). +Agents are a specific type of asset used to connect to external sensors, actuators, gateways, or services using protocols. They are added in the same manner as assets by clicking the `+` in the header of the asset tree. This will open a modal that shows the available agent types at the top of the list. You will see the generic ones: [HTTP](../agents-protocols/http.md), [WebSocket](../agents-protocols/websocket-agent.md), [MQTT](../agents-protocols/mqtt.md), [TCP](../agents-protocols/tcp.md), [UDP](../agents-protocols/udp.md) and [SNMP](../agents-protocols/snmp.md); as well as more specific ones like [Z-Wave](../agents-protocols/z-wave), [KNX](../agents-protocols/knx) or [Velbus](../agents-protocols/velbus.md). Once you create an Agent, the agent page will display the relevant attributes, required to establish an actual connection to the external world. -Some Agents have auto discovery (e.g. Z-wave) or use configuration files (e.g. KNX and Velbus). The Agent page will show a discovery button or a file selector. Once set correctly the Agent will also create an additional asset/attribute structure for all discovered or configured assets. +Some Agents have auto discovery (e.g. Z-Wave) or use configuration files (e.g. KNX and Velbus). The Agent page will show a discovery button or a file selector. Once set correctly the Agent will also create an additional asset/attribute structure for all discovered or configured assets. ![](img/create-agent1.png) ![](img/create-agent2.png) @@ -94,7 +94,7 @@ Note that you can also connect to OpenRemote through the Manager APIs without us ### Link agents and assets -If the Agent doesn't support discovery or configuration files, you will manually need to link data coming in through your agents to the attributes of your assets. We use [configuration items](../assets-and-attributes/assets-agents-and-attributes.md) on attributes such as `Agent link` and `Attribute link` for that. See the tutorial for connecting to [OpenWeatherMap via an HTTP Agent to a Weather asset](../../tutorials/open-weather-api-using-http-agent.md). +If the Agent doesn't support discovery or configuration files, you will manually need to link data coming in through your agents to the attributes of your assets. We use [configuration items](../assets-agents-and-attributes.md) on attributes such as `Agent link` and `Attribute link` for that. See the tutorial for connecting to [OpenWeatherMap via an HTTP Agent to a Weather asset](../../tutorials/open-weather-api-using-http-agent.md). ### Filtering assets and agents @@ -173,7 +173,7 @@ The alarms functionality (top right) allows you to automatically generate alarms * Generate alarms with rules: Alarms can be created by When-Then rules. * Severity: High severity alarms are automatically emailed to the assigned person. * Assigning alarms to users: Assignees always have an overview of alarms assigned to them. -* Status: The status indicates the steps in a typical workflow: Open - Acknowleged - In progress - Resolved - Closed. +* Status: The status indicates the steps in a typical workflow: Open - Acknowledged - In progress - Resolved - Closed. * Linked assets: Assets which triggered an alarm rule will be displayed to make it easier to resolve problems. * Ordering and filtering alarms. @@ -186,7 +186,7 @@ Admin users of the 'Master' realm see the Realm selector on the top right to swi ### Manager interconnect -You can link multiple instances of OpenRemote (as Gateways) to a single Central instance of OpenRemote by creating a Gateway asset in the central instance and linking the Gateway instance of OpenRemote, using the 'Manager interconnect' function. The Gateway in the central instances will show the assets of the linked Gateway instance of OpenRemote, as children of the Gateway asset and will enable bidirectional communication with its attributes. Moreover, to limit traffic, you can slect and limit the attributes shown as well as the rate at which they are synchronised with the Central instance. +You can link multiple instances of OpenRemote (as Gateways) to a single Central instance of OpenRemote by creating a Gateway asset in the central instance and linking the Gateway instance of OpenRemote, using the 'Manager interconnect' function. The Gateway in the central instances will show the assets of the linked Gateway instance of OpenRemote, as children of the Gateway asset and will enable bidirectional communication with its attributes. Moreover, to limit traffic, you can select and limit the attributes shown as well as the rate at which they are synchronised with the Central instance. See the [Edge Gateway documentation](../gateways-and-devices/edge-gateway.md) for more details. ![](img/manager-interconnect.png) @@ -262,14 +262,14 @@ _Figure 22. Auto provisioning of devices_ ### Appearance -You can restyle any realm in OpenRemote as well as adjust the map views (go to settings/appearance). You can change the logo's, use different colours, change the title and default language, or set and change the menu items. For adding map layers you can add GeoJSON files (created e.g. with https://geojson.io/). More advanced settings like visible asset and agent types on the asset and rules page, can be configured directly in a JSON file. For the options available in the JSON file and an example, check out [Configuring the Manager UI](../deploying/configuring-the-manager-ui.md). For the maps you can set the centerpoint, zoom levels and boundaries. +You can restyle any realm in OpenRemote as well as adjust the map views (go to settings/appearance). You can change the logo's, use different colours, change the title and default language, or set and change the menu items. For adding map layers you can add GeoJSON files (created e.g. with https://geojson.io/). More advanced settings like visible asset and agent types on the asset and rules page, can be configured directly in a JSON file. For the options available in the JSON file and an example, check out [Configuring the Manager UI](../deploying/configuring-the-manager-ui.md). For the maps you can set the center point, zoom levels and boundaries. ![](img/appearance-settings.png) _Figure 23. Appearance settings allow white labeling of your OpenRemote manager_ ## Manager APIs -The Manager APIs let you interact with OpenRemote without using the UI. This can be used to e.g synchronize attribute data with external clients, accessing configurations, or creating new assets. To authenticate you'll need to create a service user first on the Users page. We have three types of APIs to choose from: HTTP, MQTT, and WebSocket. +The Manager APIs let you interact with OpenRemote without using the UI. This can be used to e.g. synchronize attribute data with external clients, accessing configurations, or creating new assets. To authenticate you'll need to create a service user first on the Users page. We have three types of APIs to choose from: HTTP, MQTT, and WebSocket. ### Service users @@ -281,11 +281,11 @@ _Figure 24. Creating service users, with Username, Secret and Roles for a select ### HTTP, MQTT, and WebSocket The Manager API is compose of three APIs: HTTP, MQTT, and WebSocket: -* HTTP API is the traditional request response API with live documentation available via Swagger UI (see `https://youraddress/swagger/`) or you can look at the [demo environment swagger](https://demo.openremote.app/swagger/). +* HTTP API is the traditional request response API which is documented in the [REST API](/docs/category/rest-api) chapter. Live documentation is also available via Swagger UI (see `https://youraddress/swagger/`) or you can look at the [demo environment Swagger UI](https://demo.openremote.app/swagger/). * MQTT is a publish-subscribe API which allows connecting to our MQTT broker * WebSocket API is a publish-subscribe API that is event based. -More information on these APIs regarding formats and authentication can be found in the documentation for [Manager APIs](../manager-apis/manager-apis.md) +More information on these APIs regarding formats and authentication can be found in the documentation for [Manager APIs](../manager-apis.md) ## See Also - [Custom Deployment](../deploying/custom-deployment.md) diff --git a/docs/user-guide/manager-ui/on-mobile.md b/docs/user-guide/manager-ui/on-mobile.md index 8cb6ee6..ceb4ce4 100644 --- a/docs/user-guide/manager-ui/on-mobile.md +++ b/docs/user-guide/manager-ui/on-mobile.md @@ -10,7 +10,7 @@ The OpenRemote Manager including the Insights dashboards, are responsive and can ## OpenRemote iOS and Android App -OpenRemote includes consoles for iOS and Android. The current apps we are hosting on the [Appstore](https://apps.apple.com/nl/app/openremote-app/id1526315885?mt=8) and [Google Play Store](https://play.google.com/store/apps/details?id=io.openremote.app&pcampaignid=pcampaignidMKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1), can connect to your OpenRemote Manager instance. To use these apps for your own OpenRemote installation follow these three steps +OpenRemote includes consoles for iOS and Android. The current apps we are hosting on the [App Store](https://apps.apple.com/nl/app/openremote-app/id1526315885?mt=8) and on [Google Play](https://play.google.com/store/apps/details?id=io.openremote.app&pcampaignid=pcampaignidMKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1), can connect to your OpenRemote Manager instance. To use these apps for your own OpenRemote installation follow these three steps 1. By default you can view two types of apps for your OpenRemote instance, the 'manager' app and the 'insights' app. The 'manager' app will display all Manager pages, except the 'rules'. The 'insights' page will only show the dashboards created on the Insights page. Basically it allows you to create a simple standalone dashboard app for your users. @@ -23,7 +23,7 @@ OpenRemote includes consoles for iOS and Android. The current apps we are hostin You also can use the app for domains hosted by OpenRemote, e.g. the demo environment: ![](img/use-app-to-view-demo.png) -_Use the OpenRemote app on the Appstore and Google Play Store to access the demo and try out rules with push notification. Passwords are identical to the Realm names. Note that you have to create the rules while logged in on desktop._ +_Use the OpenRemote app on the App Store and Google Play to access the demo and try out rules with push notification. Passwords are identical to the Realm names. Note that you have to create the rules while logged in on desktop._ Once you come to the login page, you are accessing the Manager UI or Insights dashboards and seeing the mobile version. Switching between domains, apps and realms can be done by long-pressing the app icon on your home screen. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 5cf6c5c..c0ebc7e 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -134,16 +134,16 @@ const config: Config = { to: '/docs/introduction', }, { - label: 'Get Started', - to: 'https://openremote.io/get-started-iot-platform/', + label: 'Quick Start', + to: '/docs/quick-start', }, { - label: 'JavaDoc', - to: 'https://www.javadoc.io/doc/io.openremote', + label: 'REST API', + to: '/docs/category/rest-api', }, { - label: 'REST API', - to: 'https://demo.openremote.io/swagger/#/', + label: 'JavaDoc', + href: 'https://www.javadoc.io/doc/io.openremote', }, ], }, @@ -199,7 +199,6 @@ const config: Config = { label: 'Source Code', href: 'https://github.com/openremote/openremote/', }, - { label: 'OSS Licensing', href: 'https://openremote.io/open-source/',