Skip to content

Documentation/map styling #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 13, 2025
Merged

Documentation/map styling #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
81706df
Update configuring map styling
Ekhorn Apr 29, 2025
b6ef686
Move map styling docs to separate manager UI docs page
Ekhorn Apr 29, 2025
627731a
Update map settings
Ekhorn May 2, 2025
4473462
Merge branch 'main' into documentation/map-styling
Ekhorn Jun 5, 2025
87f96c1
Merge branch 'main' into documentation/map-styling
wborn Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/user-guide/manager-ui/appearance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
sidebar_position: 3
---

# Appearance Page

## Map Settings

If you want to adjust the map styling. You can change the map under Map Settings. Here you have the following options:

| Method | Description | When to use? |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Style JSON URL | Override the default map settings with a `style.json` URL (e.g. `https://api.example.com/maps/streets/style.json?key=your_key`) from a Map/Tile provider that supports MapLibre (see [providers](https://github.com/maplibre/awesome-maplibre?tab=readme-ov-file#maptile-providers)). | If you want to configure a different map quickly. |
| Import Style Settings | After configuring a Style JSON URL you can import it to include the layers allowing you to adjust the map styling. You may optionally configure a Tile server URL (to see more of a map). | If you want to be able to edit the map styling in OpenRemote, but also use an external map. |
| Realm Map Styling | You can add GeoJSON based points, lines and shapes from GeoJSON files. For creating GeoJSON files, you can use e.g. https://geojson.io/. For searching existing GeoJSON map layers, you can use https://overpass-turbo.eu/. | If you want to add map layers per realm. |
| Upload Custom `.mbtiles` | The uploaded map will be used instead of the default (see [working on maps](../../developer-guide/working-on-maps#uploading-mbtiles) for more). | If you happen to have an `.mbtiles` file and want to view a different part of the world. |
| Custom Deployment | Configure the map through [custom deployments](../deploying/custom-deployment.md#map-deploymentmap). | If you want full control over the configurations on the server (advanced usage). |

:::note
OpenRemote picks how to render the map based on the configurations set in the following order: 1) `Style JSON URL` 2) `Import Style Settings` & `Realm Map Styling` 3) `Upload Custom .mbtiles` 4) `Custom Deployment`.
:::

:::warning
Not all Map/Tile providers are fully supported, please check the provider supports MapLibre (see [maplibre providers](https://github.com/maplibre/awesome-maplibre?tab=readme-ov-file#maptile-providers)).
:::

The following tile servers have been tested.

| Provider | Supported | Not Supported |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| [Maptiler](https://maptiler.com) | Most standard maps can be imported | |
| [Carto](https://carto.com/) | Basemaps | |
| [Mapbox](https://mapbox.com/) | Tested [Classic Mapbox styles](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles) using `https://api.mapbox.com/styles/v1/mapbox/streets-v12?access_token=pk.ey...` | Import settings |
70 changes: 27 additions & 43 deletions docs/user-guide/manager-ui/manager-ui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,23 +19,7 @@ As part of the [configuring the manager UI](../deploying/configuring-the-manager
![OpenRemote Map](img/map-page.png)
_Figure 1. The Map view, here with the Demo Smart City, showing the map with different assets across the city as well as an additional map layer showing primary and secondary highways (GeoJSON). The ship is also showing its direction_

If you want to adjust the map styling. You can change the map on the appearance page. Here you have the option to change what map tiles are loaded either by configuring a tile server template URL e.g. `https://example.com/tileset/{z}/{x}/{y}` or if you have your own `.mbtiles` tiles file you can upload those instead (see [working on maps](../../developer-guide/working-on-maps#uploading-mbtiles) for more). Additionally, you can configure a custom map through [custom deployments](../deploying/custom-deployment.md#map-deploymentmap).

:::note
The tile server URL will always take precedence over `.mbtiles` files.
:::

Common tile server providers and implementations

- [Carto](https://carto.com/)
- [Mapbox](https://www.mapbox.com/)
- [Martin](https://github.com/maplibre/martin)

:::note
The base tilesets of some providers are not compatible with the default map layers in the `mapsettings.json` (see [custom deployments](../deploying/custom-deployment.md) to configure them).
:::

If you want to add map layers, you can add GeoJSON based points, lines and shapes. You can directly add GeoJSON files in settings/appearance. For creating GeoJSON files, you can use e.g. https://geojson.io/. For searching existing GeoJSON map layers, you can use https://overpass-turbo.eu/
For more see the [appearance page](./appearance.md#map-settings).

## Assets

Expand Down Expand Up @@ -66,32 +50,32 @@ _Figure 4. The Asset view in 'Edit mode' while adding an attribute_

While in `Edit asset` mode you can expand each attribute, which gives you the option to add configuration items or change existing ones. You can use configuration items to arrange access permission, parse and store data points, allow data to be used in rules, or define whether and how to show data. The available configuration items are:

| Configuration items | Description |
| :--- | :--- |
| `Access public read` | Users can read without authentication, e.g. use with public dashboard |
| `Access public write` | Users can write without authentication |
| `Access restricted read` | Restricted users can read if they have read attribute access to the asset |
| `Access restricted write` | Restricted users can write if they have write attribute access to the asset |
| `Agent link` | Define the Agent from which data is retrieved including data parsing, see [agent links](../agents-protocols/overview.md#agent-links) |
| `Attribute links` | Filter and parse multiple values retrieved with an Agent link, see [example](../../tutorials/open-weather-api-using-http-agent.md#setting-multiple-attributes-with-one-agent-link) |
| `Constraints` | Value constraints applied to the value (size/length, regex, not empty, etc.) |
| `Data points max age days` | Time period for which data is stored |
| `Forecast` | Adds [forecasting data](../rules-and-forecasting/forecasting.md), to be used in combination with 'Has predicted data points' |
| `Format` | Used for data parsing, see [format for available options](https://github.com/openremote/openremote/blob/201cc15451a2cd040a6ab9e699cbec5297821e80/model/src/main/java/org/openremote/model/value/ValueFormat.java#L37) |
| `Has predicted data points` | Enable the option to add forecasted values |
| `Label` | Add a friendly name, replacing the default name |
| `Momentary` | Button input to send the true/on/pressed/closed value when pressed; and false value when released |
| `Multiline` | Indicates that any input should support multiline text entry |
| `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 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-agents-and-attributes.md#attribute-descriptor) |
| `User connected` | Shows all restricted users which have access to this asset, see [Restricted user realm role](../identity-and-security/realms-users-and-roles.md#restricted-user-realm-role) |
| Configuration items | Description |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Access public read` | Users can read without authentication, e.g. use with public dashboard |
| `Access public write` | Users can write without authentication |
| `Access restricted read` | Restricted users can read if they have read attribute access to the asset |
| `Access restricted write` | Restricted users can write if they have write attribute access to the asset |
| `Agent link` | Define the Agent from which data is retrieved including data parsing, see [agent links](../agents-protocols/overview.md#agent-links) |
| `Attribute links` | Filter and parse multiple values retrieved with an Agent link, see [example](../../tutorials/open-weather-api-using-http-agent.md#setting-multiple-attributes-with-one-agent-link) |
| `Constraints` | Value constraints applied to the value (size/length, regex, not empty, etc.) |
| `Data points max age days` | Time period for which data is stored |
| `Forecast` | Adds [forecasting data](../rules-and-forecasting/forecasting.md), to be used in combination with 'Has predicted data points' |
| `Format` | Used for data parsing, see [format for available options](https://github.com/openremote/openremote/blob/201cc15451a2cd040a6ab9e699cbec5297821e80/model/src/main/java/org/openremote/model/value/ValueFormat.java#L37) |
| `Has predicted data points` | Enable the option to add forecasted values |
| `Label` | Add a friendly name, replacing the default name |
| `Momentary` | Button input to send the true/on/pressed/closed value when pressed; and false value when released |
| `Multiline` | Indicates that any input should support multiline text entry |
| `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 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-agents-and-attributes.md#attribute-descriptor) |
| `User connected` | Shows all restricted users which have access to this asset, see [Restricted user realm role](../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-agents-and-attributes.md#asset-type-model). Don't forget to save the asset after making changes.

Expand Down