Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
8 changes: 4 additions & 4 deletions docs/10-introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@

![image](img/architecture.jpg)

The core of the OpenRemote system is the [Manager](https://github.com/openremote/openremote/tree/master/manager), a headless Java application that forms an IoT context broker which captures the current asset state of the system. You can create a dynamic schema of your assets and their attributes in the manager, modelling the problem domain. For example, you would create Building, Vehicle, Battery, Streetlight, and Sensor assets to model an IoT system for a smart city, an energy management system, or fleet telematics.
The core of the OpenRemote system is the [Manager](https://github.com/openremote/core/tree/main/manager), a headless Java application that forms an IoT context broker which captures the current asset state of the system. You can create a dynamic schema of your assets and their attributes in the manager, modelling the problem domain. For example, you would create Building, Vehicle, Battery, Streetlight, and Sensor assets to model an IoT system for a smart city, an energy management system, or fleet telematics.

Rules can be written in Groovy, a Rules JSON, or Flow model, and dynamically deployed. Rules execute actions when matching asset state or sequence of events are detected. For example, when a mobile asset enters a geographic fence, or when your sensor is not updating anymore, you can notify a group of users via email and on their mobile devices.

Networked things and devices are connected to the manager via [Agents](https://github.com/openremote/openremote/tree/master/agent), they are the interface to 3rd party APIs and service protocols, using the services model. OpenRemote has many built-in protocols and it's easy to create new adapters. Co-locate your agents with the manager or install agents on [Edge gateways](./user-guide/080-gateways-and-devices/10-edge-gateway.md), close to devices.
Networked things and devices are connected to the manager via [Agents](https://github.com/openremote/core/tree/main/agent), they are the interface to 3rd party APIs and service protocols, using the services model. OpenRemote has many built-in protocols and it's easy to create new adapters. Co-locate your agents with the manager or install agents on [Edge gateways](./user-guide/080-gateways-and-devices/10-edge-gateway.md), close to devices.

The [Manager UI](https://github.com/openremote/openremote/tree/master/ui/app/manager) is configurable and suitable both for configuring your IoT system as well as monitoring the performance of your system. The Insight dashboard builder offers a quick way to create one page dashboard apps for your professional users who don't need access to the full manager.
The [Manager UI](https://github.com/openremote/core/tree/main/ui/app/manager) is configurable and suitable both for configuring your IoT system as well as monitoring the performance of your system. The Insight dashboard builder offers a quick way to create one page dashboard apps for your professional users who don't need access to the full manager.

The manager provides APIs for monitoring and administrating the system:

Expand All @@ -26,7 +26,7 @@ The OpenRemote [Frontend](./developer-guide/110-working-on-ui-and-apps.md) simpl
* Home automation control panel
* Smart city monitoring dashboard

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.
We support the latest HTML standards and provide [web components](https://github.com/openremote/core/tree/main/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/core/tree/main/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 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.
Expand Down
2 changes: 1 addition & 1 deletion docs/20-quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ You can quickly try the online demo with restricted access, login credentials ar
The quickest way to get your own environment with full access is to make use of our Docker images (both `amd64` and `arm64` are supported).
1. Make sure you have [Docker Desktop](https://www.docker.com/products/docker-desktop) installed (v18+).
2. Download the Docker Compose file:
[OpenRemote Stack](https://raw.githubusercontent.com/openremote/openremote/master/docker-compose.yml) (Right click 'Save link as...')
[OpenRemote Stack](https://raw.githubusercontent.com/openremote/core/main/docker-compose.yml) (Right click 'Save link as...')
3. In a terminal `cd` to where you just saved the compose file and then run:
```shell
docker-compose pull
Expand Down
10 changes: 5 additions & 5 deletions docs/architecture/10-overall-architecture.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Overall architecture

At the heart of the manager, is the [Container](https://www.javadoc.io/doc/io.openremote/openremote-container/latest/org/openremote/container/Container.html) class that manages the life cycle of all the services, including loading and starting them at launch.
Those services are defined in [manager/src/main/resources/META-INF/services/org.openremote.model.ContainerService](https://github.com/openremote/openremote/blob/master/manager/src/main/resources/META-INF/services/org.openremote.model.ContainerService)
Those services are defined in [manager/src/main/resources/META-INF/services/org.openremote.model.ContainerService](https://github.com/openremote/core/blob/main/manager/src/main/resources/META-INF/services/org.openremote.model.ContainerService)

A service is a component whose lifecycle is managed by the Container, and that provides some functionality. All services implement the [ContainerService](https://www.javadoc.io/doc/io.openremote/openremote-model/latest/org/openremote/model/ContainerService.html) interface.

Expand Down Expand Up @@ -47,7 +47,7 @@ See [Manager APIs](https://docs.openremote.io/docs/user-guide/manager-apis/) for
##### Via publishing on MQTT topics

Clients can post on `writeattributevalue` or `writeattribute` topics.
This is handled in [DefaultMQTTHandler.onPublish()](https://github.com/openremote/openremote/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/mqtt/DefaultMQTTHandler.java#L342).
This is handled in [DefaultMQTTHandler.onPublish()](https://github.com/openremote/core/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/mqtt/DefaultMQTTHandler.java#L342).

##### Via REST API

Expand All @@ -58,22 +58,22 @@ Several endpoints allow to add or update one or more attributes.
[Update attribute values](https://docs.openremote.io/docs/rest-api/write-attribute-values) - `PUT attributes`
[Update attribute values with timestamps](https://docs.openremote.io/docs/rest-api/write-attribute-events) - `PUT attributes/timestamp`

All above end up being handled by [AssetResourceImpl.doAttributeWrite()](https://github.com/openremote/openremote/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/asset/AssetResourceImpl.java#L580).
All above end up being handled by [AssetResourceImpl.doAttributeWrite()](https://github.com/openremote/core/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/asset/AssetResourceImpl.java#L580).

##### Via WebSocket API

[AttributeEvent](https://www.javadoc.io/doc/io.openremote/openremote-model/latest/org/openremote/model/attribute/AttributeEvent.html) arriving on WebSocket are handled by [ClientEventService](https://www.javadoc.io/doc/io.openremote/openremote-manager/latest/org/openremote/manager/event/ClientEventService.html).

#### From inside the system

[AssetProcessingService.sendAttributeEvent()](https://github.com/openremote/openremote/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/asset/AssetProcessingService.java#L317) can be used by any component in the system to post an [AttributeEvent](https://www.javadoc.io/doc/io.openremote/openremote-model/latest/org/openremote/model/attribute/AttributeEvent.html) for processing.
[AssetProcessingService.sendAttributeEvent()](https://github.com/openremote/core/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/asset/AssetProcessingService.java#L317) can be used by any component in the system to post an [AttributeEvent](https://www.javadoc.io/doc/io.openremote/openremote-model/latest/org/openremote/model/attribute/AttributeEvent.html) for processing.

### Events processing

Regardless of how events enter the system, they are handled through a Camel Direct component with URI "direct://AttributeEventProcessor".
This is wired to the [AssetProcessingService](https://www.javadoc.io/doc/io.openremote/openremote-manager/latest/org/openremote/manager/asset/AssetProcessingService.html), that manages the processing chain all those events go through.

[AssetProcessingService.processAttributeEvent()](https://github.com/openremote/openremote/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/asset/AssetProcessingService.java#L341) is really where all processing happens.
[AssetProcessingService.processAttributeEvent()](https://github.com/openremote/core/blob/151af17d0e502f0fa7a377cd34b8416350bc1794/manager/src/main/java/org/openremote/manager/asset/AssetProcessingService.java#L341) is really where all processing happens.

A lock is immediately taken on the asset (assetId based) and during this lock:
- [Asset](https://www.javadoc.io/doc/io.openremote/openremote-model/latest/org/openremote/model/asset/Asset.html) is retrieved from DB
Expand Down
10 changes: 5 additions & 5 deletions docs/architecture/20-manager-endpoints-and-file-paths.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ The following list shows the file paths used by our Docker containers; these can
* `$OR_APP_DOCROOT` - Location of well known UI apps and shared resources; Default: `/opt/web`
* `$OR_CUSTOM_APP_DOCROOT` - Location used to load paths that aren't well known which allows custom web content to be served; Default: `/deployment/manager/app`
* `$OR_FIREBASE_CONFIG_FILE` - Location of Firebase Cloud Messaging configuration file which allows push notification functionality `/deployment/manager/fcm.json`
* `$OR_KEYCLOAK_GRANT_FILE` - Location of [OAuth Grant](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/auth/OAuthGrant.java) in `json` representation which is used internally by the manager to communicate with Keycloak (in order to provision users, tenants, etc.); Default: `/deployment/manager/keycloak.json`
* `$OR_LOGGING_CONFIG_FILE` - Path of custom `JUL` logging config file; Default: `/deployment/manager/logging.properties`, falls back to built-in config if not specified or not found which can be found [here](https://github.com/openremote/openremote/blob/master/manager/src/main/resources/logging.properties).
* `$OR_MAP_TILES_PATH` - Path of `mbtiles` map data file; Default: `/deployment/map/mapdata.mbtiles`, falls back to built-in map data (`/opt/map/mapdata.mbtiles`) if not specified or not found which can be found [here](https://github.com/openremote/openremote/tree/master/manager/src/map)
* `$OR_MAP_SETTINGS_PATH` - Map settings path to `json` configuration for styling the map; Default: `/deployment/map/mapsettings.json`, falls back to built-in settings (`/opt/map/mapsettings.json`) if not specified or not found which can be found [here](https://github.com/openremote/openremote/tree/master/manager/src/map)
* `$OR_KEYCLOAK_GRANT_FILE` - Location of [OAuth Grant](https://github.com/openremote/core/blob/main/model/src/main/java/org/openremote/model/auth/OAuthGrant.java) in `json` representation which is used internally by the manager to communicate with Keycloak (in order to provision users, tenants, etc.); Default: `/deployment/manager/keycloak.json`
* `$OR_LOGGING_CONFIG_FILE` - Path of custom `JUL` logging config file; Default: `/deployment/manager/logging.properties`, falls back to built-in config if not specified or not found which can be found [here](https://github.com/openremote/core/blob/main/manager/src/main/resources/logging.properties).
* `$OR_MAP_TILES_PATH` - Path of `mbtiles` map data file; Default: `/deployment/map/mapdata.mbtiles`, falls back to built-in map data (`/opt/map/mapdata.mbtiles`) if not specified or not found which can be found [here](https://github.com/openremote/core/tree/main/manager/src/map)
* `$OR_MAP_SETTINGS_PATH` - Map settings path to `json` configuration for styling the map; Default: `/deployment/map/mapsettings.json`, falls back to built-in settings (`/opt/map/mapsettings.json`) if not specified or not found which can be found [here](https://github.com/openremote/core/tree/main/manager/src/map)
* `/deployment/manager/extensions` - Location of custom java code that is added to the classpath of the manager during startup
* `$OR_PROVISIONING_DOCROOT` - Location of provisioning directory which can contain the following sub-directories of `json` representations to be automatically provisioned into the manager during a clean install setup:
* `assets` - Sorted alphabetically, each `json` file should contain exactly 1 asset in `json` representation
* `consoleappconfig`- Each `json` file should contain exactly 1 [ConsoleAppConfig](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/apps/ConsoleAppConfig.java) in `json` representation
* `consoleappconfig`- Each `json` file should contain exactly 1 [ConsoleAppConfig](https://github.com/openremote/core/blob/main/model/src/main/java/org/openremote/model/apps/ConsoleAppConfig.java) in `json` representation
4 changes: 2 additions & 2 deletions docs/architecture/30-security.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Security

## Realm clients
For each realm created within the Manager (via UI, provisioning code or REST API) a client called `openremote` is automatically created and all the roles defined in [ClientRole](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/security/ClientRole.java) are automatically added to this client.
For each realm created within the Manager (via UI, provisioning code or REST API) a client called `openremote` is automatically created and all the roles defined in [ClientRole](https://github.com/openremote/core/blob/main/model/src/main/java/org/openremote/model/security/ClientRole.java) are automatically added to this client.

## Service users
Service users are actually implemented using Keycloak clients with `Service account enabled`, this creates an 'invisible' user account with a username in the format `service-account-${clientId}` (invisible because they don't show in the user list in the Keycloak admin console). The client that is generated when a service user is created will also have the all the roles defined in [ClientRole](https://github.com/openremote/openremote/blob/master/model/src/main/java/org/openremote/model/security/ClientRole.java) added to this client.
Service users are actually implemented using Keycloak clients with `Service account enabled`, this creates an 'invisible' user account with a username in the format `service-account-${clientId}` (invisible because they don't show in the user list in the Keycloak admin console). The client that is generated when a service user is created will also have the all the roles defined in [ClientRole](https://github.com/openremote/core/blob/main/model/src/main/java/org/openremote/model/security/ClientRole.java) added to this client.
2 changes: 1 addition & 1 deletion docs/architecture/50-asset-location-tracking.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ When a geofence is triggered on an asset then the asset should update its own lo
**By using geofence triggers in this way the handling of all location tracked assets can be processed in the same way i.e. the manager rules can compare location asset state changes irrespective of how the asset provides the location data.**

## Geofence Asset Adapters
Refer to the source code for details of the [GeofenceAssetAdapter](https://github.com/openremote/openremote/blob/location/manager/src/main/java/org/openremote/manager/rules/geofence/GeofenceAssetAdapter.java) and how it is used. Currently there is one implementation:
Refer to the source code for details of the [GeofenceAssetAdapter](https://github.com/openremote/core/blob/location/manager/src/main/java/org/openremote/manager/rules/geofence/GeofenceAssetAdapter.java) and how it is used. Currently there is one implementation:

### ORConsoleGeofenceAssetAdapter (Android and iOS consoles)
An asset will use this adapter if it matches the following criteria:
Expand Down
2 changes: 1 addition & 1 deletion docs/developer-guide/010-preparing-the-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,5 +38,5 @@ Ensure that you have the `JAVA_HOME` environment variable set to the path of JDK

## See also

- [Next 'Get Started' step: Build the code and run the manager](https://github.com/openremote/openremote/blob/master/README.md)
- [Next 'Get Started' step: Build the code and run the manager](https://github.com/openremote/core/blob/main/README.md)
- [Get Started](https://openremote.io/get-started-iot-platform/)
2 changes: 1 addition & 1 deletion docs/developer-guide/020-setting-up-an-ide.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ For formatter plugins and IDE settings, see [Code formatting with Spotless](./02

##### Grep Console Styling

The log messages of the running application can be colour-highlighted with the [GrepConsole plugin](https://plugins.jetbrains.com/plugin/7125-grep-console) and our [configuration](https://github.com/openremote/openremote/tree/master/tools/intellij).
The log messages of the running application can be colour-highlighted with the [GrepConsole plugin](https://plugins.jetbrains.com/plugin/7125-grep-console) and our [configuration](https://github.com/openremote/core/tree/main/tools/intellij).

- Locate XML style config for Grep Console in openremote/tools/intellij
- Choice the default or dark styling config
Expand Down
Loading
Loading