Disclaimer: This guide is a work-in-progress and not complete!
Mepo is a fast, simple, and hackable OSM map viewer for desktop & mobile Linux devices (like the PinePhone, Librem 5 etc.) and both environment's various user interfaces (Wayland & X inclusive). It's interface presents an SDL interactive application and auxillary features are built out in scripts. The basic interface is essentially a OSM map that can be panned, zoomed, mainuplated, and overlayed via 'pins' which are arbitrary points on the map which can be added by the user to mark locations. Being a good unix citizen, the core application does one thing well, only focusing on displaying the map and visual overlays, and has no extra functionality; however Mepo plays well with other applications and is scriptable and very customizable through Mepolang.
For end-users not intersted in customizing the behvaior of Mepo, the application is bundled with sensible defaults including a default set of keybindings, touch-compatible configuration, and scripts written in plain shell which enable features such as POI searches, routing, and more. Throughout the rest of this guide it will be assumed the user is making use of the default configuration and has done no customization; but its important to realize there is a hard disticntion between the core SDL application, Mepo, and its default configuration and scripts which are bundled by default.
Using Mepo on mobile linux devices such as the Pinephone, Librem 5, and postmarketOS devices and similar is a primary usecase. Take note of the following shortcuts:
Ordinary desktop usage is supported. Ordinary one finger hotkeys reference in the mobile section also apply on the desktop; and in addition numerous hotkeys exist such as panning with vim-style keys and direct hotkeys to launch various scripts. You can reference the default hotkeys by studying the default configuration.
TODO Add visual diagram explaining difference components of UI (buttonbar, bottom bar, pin overlay, pins, etc.)
The UI feature a bar of buttons in the default configuration indicated
as text aligned in a bar on the bottom of the screen. Under the hood this is
actually built out using the
bind_button mepolang command; so if you want
to add your own custom buttons (tied to userscripts, etc.) this is doable.
Here's an explanation of the provided script accessible in the button bar in the default config:
Since most auxillary features such as routing, POI searches, etc. are built out in shellscripts (which utilize dmenu, rofi etc.); the central menu provides a central way to launch different scripts on mobile via touch or on the desktop without having to rember numerous hotkeys.
Here's an explation of the options are available in the central menu:
Points of intrest within the current viewport (bounding-box) can be searched both via Nominatim or via Overpass using the default included scripts. Each of these methods has its advantages and disadvantages. Generally speaking, for specific name-based searches within a region, you should use Nominatim; while for flexible OSM-tag-based searches you should use Overpass.
As described above, Nominatim excels at name based searches. For example if you wanted to find a restraunt called "Joe's Pizza" you could type this directly into the Nominatim POI search script prompt. Or similarly to find a starbucks, you could just type in "starbucks" in the Nominatim prompt.
Meanwhile, Overpass is more powerful and suited then Nominatim for
POI searches based on OSM tags; for example if you wanted to find
all coffeshops, (rather then just a specific name of a coffeshop such as
"starbucks" in the previous example) you could search for the general
[amenity=cafe]. This will find all OSM relations matching this
tag within the current bounding box. A number of prepopulated OSM tags
are available within the provided Overpass script; however if you want
to search any custom OSM tag, simply enter it and this will work just
TODO Routing placeholder. Explain graphhopper & OSM relation scripts here.
The map view will start wherever is set in the default configuration or optionally you can overload this default location (see the next section for autoloading preferences).
To reposition the map while mepo is already running you can use the
provided menu entry
Relocate map: via Nominatim entry to search
nominatim to determine a new location to set for the map. Using this
script simply enter the name of a region (city, state, country, etc.) and
Nominatim will be queried for matching targets. Select a target to
reposition the map accordingly.
Within the default config, the file located at
~/.mepo/bookmarks is loaded
from the filesystem by default when starting mepo. You can put user-specific
configuration here that will override the default configuration.
center_on_coords 42.3608 -71.0573; pin_groupprefset 3 active 1; pin_add 3 0 42.355 -71.0780 [foopin] [foopin]; prefset zoom 15;
In the above example, the map is repositioned to Boson, MA, US and an arbitrary bookmark pin named foopin is placed on the map.
If you have already used Mepo to download tiles, either interactively or
mepo_dl.sh script as described above; you may use Mepo entirely
offline by setting the preference
echo "prefset tile_cache_network 0;" | mepo -i
You'll see this noted noted in the download bar as
This mode is helpful if you have bandwidth limitations (e.g. for your data plan or similar) and want to make sure Mepo does not make any network requests.
It's a common use case to need to download an entire block / bounding box of tiles while online before going offline. For example, say if you want to use your phone with Mepo but are not sure you'll not have internet access at your destination.
To facilitate downloading of tiles, Mepo features a non-interactive CLI
accessible through using the
-d flag. This flag should be suffixed with
a list of 6 comma separate parameters (no whitespaces) in the form of
lat_a,lon_a,lat_b,lon_b,zoom_min,zoom_max. Zoom min and max can range
For example, to download a bounding box:
This may be a bit more involved then you would like to get, so as an
alternative you can use the provided
mepo_dl.sh script which provides
a prompt-driven dialog which queries Nominatim
to determine the bounding box to download and then feeds this into
Run this script as:
See below section for information about offline usage.
Mepolang is Mepo's command language API for IPC that can be sent to its
process via STDIN continually. Through this mechanism you can control
Mepo: using an external script, by simply piping in a configuration
on boot, or by using a FIFO (eventually). Upon the 1.0 release it is
planned that there will be two commands included to run Mepo:
mepo_run.sh will just be a script that runs
cat default_config | mepo.
Many of Mepo's commands play nice together. A good place to look to
understand Mepolang's utilization is the default config. For
bind_key actually also takes Mepolang text to run as an
argument. Similarly the result of
shellpipe, runs Mepolang text given
the STDOUT result of a (user) shellscript.
[ square brackets ]to create a multiword token.
3.77) or whole (e.g.
-22.22or positive like
commandname textarg [multi word arg] 2; commandname2 arg 8.373 anothertextarg;
By default debug messages are disabled. To start mepo with debugging via
STDERR use the CLI flag
-e. E.g. as: