View on GitHub

OSM Scout Server

Maps server providing tiles, geocoder, and router
English español français svenska

OSM Scout Server

OSM Scout Server can be used as a drop-in replacement for online map services providing map tiles, search, and routing. As a result, an offline operation is possible if the device has a server and map client programs installed and running. OSM Scout Server is mainly developed for Sailfish OS, but could be used on a regular Linux system as a console or QtQuick application.

Here, the user guide is provided with the description of setting up the server and popular clients for offline operation on Sailfish OS device. For developer’s info, see GitHub page of the project and it’s README.

Mode of operation

In contrast to offline navigation solutions provided by other applications, the server is one of the two parts that are required by users. Users would need to have the server and a client accessing the server running simultaneously and communicating with each other.

After initial setup, users would mainly have the server running in the background while accessing maps and getting navigation instructions through client. The server’s GUI is only needed for managing maps on device.

On Sailfish OS, the normal mode of operation would require server running as one of the applications showing a cover and client opened as needed. Alternatively, the server can be activated automatically by systemd on request by the client. Such mode of operation allows client to access the server without exposing GUI of the server.

Setting up the server

There are several steps required to setup the server. The following guide is aimed at Sailfish OS users.

Modules

The server uses modular approach. While the current version of the server does not require any modules in default configuration, some of the modules maybe required for operation in user selected configuration. The modules, if needed, are checked for on each start of the server. If needed, the server will request the module installation. In this case, please proceed to Jolla Store or OpenRepos and install the corresponding module. After installation of the modules, please restart the server, if instructed by the server. The modules are used automatically and don’t have to be started by users.

Note that earlier used OSM Scout Server Module: Route is now incorporated into the main server executable and can be uninstalled when using OSM Scout Server of version 1.8 or higher.

Storage

OSM Scout Server needs to store maps. The storage requirements could be significant. To store maps and manage them, a separate folder is required. Please note that, as a part of the managing, OSM Scout Server can delete, on your command, files from that folder. Thus, its important to allocate such folder and assign it to OSM Scout Manager. See Storage allocation tutorial for example on how to do it with the help of FileCase.

Map Manager

To download, update, and remove maps, use Map Manager. The initial subscription of the maps and their download is described in Map Manager Download tutorial.

After the maps are downloaded, you are ready to proceed with the configuration of your map access client. Select the corresponding section below to see how to configure it.

Language selection

The server uses natural language processing (NLP) library that covers processing of addresses in large number of languages - libpostal. To limit usage of resources, please specify languages as shown in Language selection tutorial.

Profile

To simplify configuration, OSM Scout Server uses profiles. You are asked to select profile on the first start. Later, you can select profile as shown in the Profile selection tutorial.

Clients using MapboxGL tiles (sometimes referred as vector tiles) are supported by the default OSM Scout Server configuration. At the moment of writing, its WhoGo Maps and sports application Laufhelden.

Clients that request rendered tiles from the server, such as Poor Maps and modRana, would require selection of OSM Scout Server profile that includes raster tiles. Please adjust the profile if you want to use these clients.

Settings

There are multiple settings that can be useful to tune the operation of the server. Among other settings, this includes language preference, units, and whether the server is activated automatically. See some examples in Settings examples.

Setting up the client

After the server has been setup and the maps downloaded, the access to the server has to be configured in the client(s).

For Pure Maps, select “Offline” profile in main menu of Pure Maps. This will configure all services to access OSM Scout Server.

For WhoGo Maps, please follow instructions below for Poor Maps. Just replace ‘Basemaps’ selection with selection of ‘Maps’ in WhoGo Maps menu.

For Poor Maps, instructions are here.

For modRana, instructions are here.

After the client is setup, you can use them together with OSM Scout Server for offline maps access.

Running

As described above, when using OSM Scout Server, you need to run the server and client at the same time. There are two ways to do it:

Automatic

If you enabled automatic activation then all you have to do is to start the client. The client will access either the server running as GUI application in the background or, if its not started, the server running as a service.

Manual

Debugging issues

If you have issues with running OSM Scout Server, such as problems with accessing it from the client, consider enabling logging of info messages. This can be done in the Settings.

Geocoder

Parsers

Parsers are responsible for splitting the entered search string into the address. Geocoder works using libpostal for parsing entered search string and is expected to parse the address in its natural form for the used language/country combination. In addition to automatic parsing by libpostal, one can use “primitive” parser that takes a search string, splits it by comma, and constructs the hierarchy assuming that the search string was entered by listing the address or POI from the finest details to the region. For example,

house_number, street, city

As libpostal, primitive parser supports postal codes. For that, enter postal code using post: prefix for the code in any part of the hierarchy or just alone to search by the postal code. For example,

house_number, street, city, post: 12345

or post:12345. Note that spaces between keyword post: and the postal code are ignored.

Tags and aliases

To distinguish types of objects, the geocoder uses tags that are imported from OpenStreetMap. Tags are also associated with aliases in a language-dependent manner. The tags and their aliases are listed in tags.

Aliases and the tags are imported from the list of special phrases maintained for Nominatim at https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases. If you find something missing or want to correct it, please correct it at the source.

Implementation of automatic activation

To enable automatic activation, OSM Scout Server interfaces with systemd by creating service and socket files in the home directory of the user running the server. In addition, the socket activation is enabled by running systemctl. In Sailfish, that results in creating or modification of

/home/nemo/.config/systemd/user/osmscout-server.service
/home/nemo/.config/systemd/user/osmscout-server.socket
/home/nemo/.config/systemd/user/user-session.target.wants

If you wish to remove the automatic activation manually, run

systemctl --user disable osmscout-server.socket

and then remove service and socket files. In Sailfish, remove

/home/nemo/.config/systemd/user/osmscout-server.service
/home/nemo/.config/systemd/user/osmscout-server.socket