Skip to content

Update custom map docs #78

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 1 commit into from
Apr 24, 2025
Merged

Update custom map docs #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
58 changes: 50 additions & 8 deletions docs/developer-guide/working-on-maps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,61 @@ sidebar_position: 6

## Vector maps (Mapbox GL)

The manager has built in support for `Mapbox GL` and can serve vector tile data. For this to work please ensure that you have the following files available in the deployment folder:
The manager has built in support for `Mapbox GL` and can serve vector tile data. Tiles can be configured from the appearance page or through a custom deployment. Please ensure to check the following:

### Uploading MBTiles

The `*.mbtiles` file size must be equal or less than the specified tile upload limit. The default limit is 30MB, this can be increased with `OR_CUSTOM_MAP_SIZE_LIMIT`. The tiles should adhere to the [MBTiles specification](https://github.com/mapbox/mbtiles-spec/blob/master/1.3/spec.md).

```sh
OR_CUSTOM_MAP_SIZE_LIMIT: 1000000000 # 1GB
```

The `*.mbtiles` file is a SQLite database under the hood. OpenRemote validates that this contains the required metadata. In case something is missing in the metadata table (see [troubleshooting](#troubleshooting)).

### Custom Deployment

Make sure the deployment folder contains the following files:

* `map/mapsettings.json` - Contains settings related to the map tiles source data and also UI rendering settings (e.g. center point of map when first loaded)
* `map/mapdata.mbtiles` - Contains the vector map data (adding it here will override the demo map for Rotterdam, located in the manager folder `src/map`)
* `map/mapdata.mbtiles` - Contains the vector map data (adding it here will override the demo map for Rotterdam, located in the manager folder `src/map`)

If you have the map data and/or settings in a different location then please ensure that the manager environment variables are set also:
```shell
MAP_TILES_PATH=../deployment/map/mapdata.mbtiles
MAP_SETTINGS_PATH=../deployment/map/mapsettings.json
```

### Troubleshooting

If the `*.mbtiles` have failed to upload, load- or display correctly please make sure to check all the required metadata fields are present.
```sh
sqlite3 -cmd "SELECT * FROM metadata;" example.mbtiles
```

Update or insert `bounds` into the metadata table.
```sh
sqlite3 -cmd "INSERT INTO metadata (name, value) VALUES ('bounds', '5.144469,51.245319,5.783558,51.647744') ON CONFLICT(name) DO UPDATE SET value = excluded.value;" example.mbtiles
```

<details>
<summary>See required fields</summary>

```
name|eindhoven # Currently ignored
attribution|<a href="https://www.maptiler.com/copyright/" target="_blank">&copy; MapTiler</a> <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap contributors</a>
bounds|5.144469,51.245319,5.783558,51.647744
center|5.464014,51.446532,7
format|pbf # Currently ignored
maxzoom|14
minzoom|0
json|{...}
```

</details>

## Raster maps (Mapbox JS)
If you are working on raster maps (Mapbox JS) then you will need to have the `map` Docker container running, this container serves the raster map tiles from the vector map data.
If you are working on raster maps (Mapbox JS) then you will need to have the `map` Docker container running, this container serves the raster map tiles from the vector map data.

The container can be started by using the `dev-map.yml` profile (see [here](docker-compose-profiles.md)) or you can add a `map` service to an existing custom project profile (copy the `dev-map.yml` as a template).

Expand All @@ -42,10 +84,10 @@ We currently do not have our own pipeline for extracting/converting OSM data int
From that mbtiles file you can extract smaller tilesets with the following procedure:

1. Rename the source tileset file `input.mbtiles`
1. Create Docker container with `node` and `python` with dir containing `input.mbtiles` volume mapped: `docker run -it --rm -v PATH_TO_INPUT_MBTILES_DIR:/mapdata nikolaik/python-nodejs:python3.8-nodejs12 bash`
1. Install tilelive converter:
2. Create Docker container with `node` and `python` with dir containing `input.mbtiles` volume mapped: `docker run -it --rm -v PATH_TO_INPUT_MBTILES_DIR:/mapdata nikolaik/python-nodejs:python3.8-nodejs12 bash`
3. Install tilelive converter:
`npm install -g --unsafe @mapbox/mbtiles @mapbox/tilelive`
1. Select and copy boundary box coordinates of desired region (these are the BOUNDS used in the next command; they must be in format [W,S,E,N] e.g. `4.91, 51.27, 5.84, 51.77`):
4. Select and copy boundary box coordinates of desired region (these are the BOUNDS used in the next command; they must be in format [W,S,E,N] e.g. `4.91, 51.27, 5.84, 51.77`):
https://tools.geofabrik.de/calc/#tab=1 (use the coordinates in 'Simple Copy' and add the commas)
1. Extract the desired region (adjust the zoom levels as required and optionally add `--timeout=Nms` if the task times out): `tilelive-copy --minzoom=0 --maxzoom=14 --bounds="FILL_BOUNDS_HERE" /mapdata/input.mbtiles /mapdata/output.mbtiles`
1. Rename `output.mbtiles` into `mapdata.mbtiles`
5. Extract the desired region (adjust the zoom levels as required and optionally add `--timeout=Nms` if the task times out): `tilelive-copy --minzoom=0 --maxzoom=14 --bounds="FILL_BOUNDS_HERE" /mapdata/input.mbtiles /mapdata/output.mbtiles`
6. Rename `output.mbtiles` into `mapdata.mbtiles`
48 changes: 32 additions & 16 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 @@ -12,15 +12,31 @@ 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 would 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.
The `Map` page will show your map. You can pan, zoom, and tilt the map. On the map all assets are shown which have a location (disable it by setting the configuration item `show on dashboard` to `false`). Assets can have static or dynamic locations (e.g. a car, boat or plane). You will see the direction an asset is facing or moving to 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.

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/
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.

![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/

## Assets

The `Assets` page lets you view and modify assets and their attributes. You will see the asset tree structure on the left, and the details of the selected asset on the right. The asset page contains an Info panel, an Attributes panel, a Location panel (if any) and a History panel.
Expand Down Expand Up @@ -111,27 +127,27 @@ In the asset tree you can multi-select assets and collectively add them as child

The Rules page (only available on desktop screen sizes) allows you to build three types of rules:
* [WHEN-THEN Rules](#when-then-rules): When certain conditions created with asset attributes are met, then trigger an action for another attribute.
* [FLOW](#flow-rules): Process attributes and convert them into new attributes with a simple drag-and-drop interface.
* [FLOW](#flow-rules): Process attributes and convert them into new attributes with a simple drag-and-drop interface.
* [GROOVY](#groovy-rules): programming any advanced logic, using attributes in the system.
All rules can be set to only be active during a (recurring) event set with the scheduler.

Note that you need to add the configuration item 'Rule state' to both the attributes used on the left-hand-side and right-hand-side of the rule, to make the rule actually fire an action.

### When-Then Rules

When-Then rules use conditions set for attributes to trigger an action for another attribute. The actions do not only include controlling assets, but can also be used to send e-mails or push notifications to mobile apps (using the OpenRemote consoles), or use web hooks.
When-Then rules use conditions set for attributes to trigger an action for another attribute. The actions do not only include controlling assets, but can also be used to send e-mails or push notifications to mobile apps (using the OpenRemote consoles), or use web hooks.

![](img/when-then-example.png)
_Figure 7. A When-Then example, which shows how, on the When-side an asset type can be selected, while on the Then-side the action, in this case a push notification, is defined._

The frequency on which rules trigger as well as a timer schedule can be set.
The frequency on which rules trigger as well as a timer schedule can be set.
The rule frequency, a dropdown on the upper right of each 'Then' panel defines how frequently a rule can trigger. For example 'Always' means every time the condition is triggered, but only after the condition has been false (so not continuously on being true).
The scheduler (right next to the name field of the rule) lets you set an occurrence period as well as repeat that occurrence.

![](img/time-scheduler-rules-trigger-frequency.png)
_Figure 8. The Rules trigger frequency (right) as well as time scheduler (left) defines when rules are triggered and active. The scheduled example sets the rule to be active until June 20 2022, only on weekdays._

See the [When-Then rules](../rules-and-forecasting/when-then-rules.md) documentation for more details.
See the [When-Then rules](../rules-and-forecasting/when-then-rules.md) documentation for more details.

### Flow Rules

Expand All @@ -155,7 +171,7 @@ As an admin user of the system who can access all realms, you have the option to

The Insights page (see figure 11) allows you to create multiple dashboards within the manager UI. You can:
* Define the dashboard behaviour for different screen sizes and optimise the design for a specific screen.
* Share dashboards with other users even as standalone app, or keep your dashboard private.
* Share dashboards with other users even as standalone app, or keep your dashboard private.
* Make dashboards public. Note this requires assets to be set as 'public' and attributes as 'public read'.
* Share via the [iOS or Android console](on-mobile.md) and benefit push notifications (see figure 12).
* Use eight types of widgets (or [extend with your own](../../developer-guide/adding-widgets-on-insights.md)): Chart, KPI, Gauge, Image, Map, Table, Attribute (with control) and Gateway.
Expand Down Expand Up @@ -197,7 +213,7 @@ _Figure 15. Next to interconnecting you can choose which asset attributes are ac

### Gateway tunnels

On top of the 'Manager Interconnect' functionality, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. See the [Edge Gateway documentation](../gateways-and-devices/edge-gateway.md) for more details.
On top of the 'Manager Interconnect' functionality, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. See the [Edge Gateway documentation](../gateways-and-devices/edge-gateway.md) for more details.

![](img/create-gateway-tunnel.png)
_Figure 16. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._
Expand All @@ -222,15 +238,15 @@ _Figure 18. The account page with contact details (left) and reset passwords (ri

### Users and access configuration

If you have the correct access rights (role or permissions) for it you can also create new Users for the selected realm and set the roles and access of a user.
If you have the correct access rights (role or permissions) for it you can also create new Users for the selected realm and set the roles and access of a user.

#### Link assets to users
#### Link assets to users

By linking assets to users, the system will understand which users are connected to a specific asset. Consequently you can create a rule such as "When any temperature sensor measures more than 100 degree, send an email to the linked user".

#### Restricted user

When, next to linking an asset to a user, you also set the Realm role to 'Restricted User', users will only have access to the assets they are linked to. Note that you additionally have to indicate on the assets which attributes of the asset they have access to. To do that, set the configuration item 'Access restricted user read/write' on the attribute ([see 'Configure attributes'](#configure-attributes)).
When, next to linking an asset to a user, you also set the Realm role to 'Restricted User', users will only have access to the assets they are linked to. Note that you additionally have to indicate on the assets which attributes of the asset they have access to. To do that, set the configuration item 'Access restricted user read/write' on the attribute ([see 'Configure attributes'](#configure-attributes)).

![](img/creating-users.png)
_Figure 19. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._
Expand All @@ -246,7 +262,7 @@ _Figure 20. Roles are made of a set of permissions_

Only the Master realm Admin user can create `Realms` by accessing the master realm `https://youradress/manager`. Realms are separated projects which can be used for individual users or customers of your platform. Individual Realms can be reached at `https://youradress/manager/?realm=realmname`. Note that the Master realm Admin user should have created a new user in this realm first, before the individual Realm can be accessed.

You can create a realm by adding a `realmname` name (single word, lower case letters), and a `Friendly name`. You can (temporarily) disable realms, which blocks access for any user.
You can create a realm by adding a `realmname` name (single word, lower case letters), and a `Friendly name`. You can (temporarily) disable realms, which blocks access for any user.

![](img/realms.png)
_Figure 21. Realms can be created to manage multiple independent projects within one OpenRemote instance_
Expand All @@ -262,9 +278,9 @@ _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 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, set and change the menu items, and use multiple languages for notifications to support personal language preferences.
You can change the logo's, use different colours, change the title and default language, set and change the menu items, and use multiple languages for notifications to support personal language preferences.

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.

Expand Down