ben/brouter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3

Restrucuture documentation to smaller parts

Browse source
This commit is contained in:
Manuel Fuhr 2021-12-29 08:49:47 +01:00
parent 76f20ca864
commit 80681b78c6
12 changed files with 300 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

146
docs/users/android_advanced.md Normal file
View file

@ -0,0 +1,146 @@
---
parent: Using BRouter
nav_order: 2
---
# Android advanced configuration
### Directory structure
BRouter uses several subdirectories inside the base directory.
| directory | description |
| --------------------------------- | -------------------------------------------- |
| `<basedir>/brouter` | |
| `<basedir>/brouter/modes` | routing-mode/profile mapping and route cache |
| `<basedir>/brouter/profiles2` | lookup-table and routing-profiles (\*.brf) |
| `<basedir>/brouter/segments4` | **routing data files (\*.rd5)** |
| `<basedir>/brouter/import` | allow a small file exchange with other apps |
| `<basedir>/brouter/import/tracks` | place the `nogo*.gpx` files here |
`modes` contains `serviceconfig.dat` which defines _routing-mode_ /
_routing-profile_ mapping and cached route results which are used for
recalculations.
`profiles2` contains `lookup.dat` (OSM tag access), `serverconfig.txt` and
_routing-profiles_.
`segments4` contains `storageconfig.txt` and routing data files (\*.rd5). You
can download them using the _Download Manager_ or as described in [Download
Routing Segments](users/download_segments.md).
### Configuration files
#### serverconfig.txt
`serverconfig.txt` is used to configure download information for routing
profiles and routing segments.
#### serviceconfig.dat
`serviceconfig.dat` is used to configure mapping between _routing-mode_ and
_routing-profile_.
#### storageconfig.txt
`storageconfig.txt` is used to specifiy additional paths which BRouter should
use.
* `secondary_segment_dir` points to an additional directory containing routing
data files. This can be located anywhere.
When searching for datafiles, both the download manager and the router first
look in the primary (brouter/segments4) and then in the secondary directory.
On the other hand, the download manager always writes new datafiles to the
primary directory, so the secondary directory is read-only.
You can move datafiles downloaded by the download-manager to the secondary
directory, by using a file manager, in order to free disk space on the
internal card.
* `additional_maptool_dir` points to a directory that should be scanned for
maptool-installations in addition to the standard-guesses.
#### Redirect files
When using the _file interface_ with waypoints from other app's storage BRouter
tries to write the calculated tracks to the app storage. Depending on the
Android version this won't work. BRouter can be configured to write tracks to a
different directory by creating a `brouter.redirect` file which contains a
single line with the absolute path to the folder where the tracks should be
written.
* For LocusMap `brouter.redirect` has to be located in `Locus/mapItems`
* For OruxMaps `brouter.redirect` has to be located in `oruxmaps/tracklogs`
* For OsmAnd `brouter.redirect` has to be located in `osmand/tracks`
## Using nogo-areas
There's a special naming-convention to specify nogo-areas:
`nogo[radius] [name]` defines a nogo-area, where radius (in Meter) is optional
and defaults to 20m, and the name is also optional. So `nogo`, `nogo1000`, `nogo
roadblock`, `nogo200 badferry` are all valid names for nogo-waypoints.
The effect is that BRouter searches a route that avoids the area defined by the
position and the radius of the nogo-area.
Nogo-areas are used when routing via _service interface_ and _file interface_.
When using the _file interface_ you will get a nogo-dialog allowing to de-select
them if nogo-waypoints are found in the waypoint-database. This de-selection can
also be bound to a service mode using the _Server Mode_ button to make it
effective using the _service interface_ as well, but initially, every nogo-area
is effective in the _service interface_.
Nogo-areas can be used either to account for real obstacles or to enforce
personal routing preferences.
## Routing via _file interface_
The other option is using the BRouter app to calculate a route. This is the
prefered option when calculating long-distance-routes that would not finish
within the 60 seconds timout if calculated via the _service interface_.
To do this, start the BRouter app, select two or more waypoints and then start
the route calculation. BRouter either reads waypoints from the `import` folder
or tries to read waypoints from other map tools if it has the required
permission. These waypoints are called _Favorites_ in OsmAnd, _POIs_ in Locus or
_Waypoints_ in Oruxmaps and allow to associate a location with a name.
If your waypoint database contains a `from` and `to` waypoint the waypoint
selection will be skipped. BRouter also uses `via1`, ..., `via9` as via
waypoints.
If a route is calculated, it is stored as `brouter0.gpx`. Depending on the
waypoint database and permissions BRouter stores the route in
`<basedir>/import/tracks` or in the map tool track directory. If started once
more with identical input, BRouter will store a second route broute1.gpx for the
first alternative and so on.
### Permission issues
If using the file interface BRouter needs to access the files from other apps.
Depending on your android version, your BRouter version and location of other
apps locations it will be impossible to read or write those files.
## Mixed operation: _timeout-free recalculations_
You can combine both operation modes (_service interface_ + _file interface_ to
become able to calculate very long distances, but make use of the advantages of
the service interface as well, especially the dynamic recalculations if you get
off the track, without running into the 60 seconds timeout.
To support this, BRouter can do _timeout free recalculations_. It works by
initially calculating a track to your destination and binding it to one or more
routing-modes using the _Server Mode_ button. This way, BRouter stores a
_reference track_ in the `brouter/modes` subdirectory.
If afterwards a route to the exact same destination is calculated via the
service interface, BRouter uses a special calculation mode that makes use of the
reference track for faster processing that is guaranteed to give a result within
60 seconds. _Exact same_ destination means withing 5m, so best use the same
waypoint for re-calculating that you used for the initial calculation.
This way you can follow a long distance route via the _service interface_,
enjoying automatic recalculations if you get off the track.

92
docs/users/android_quickstart.md Normal file
View file

@ -0,0 +1,92 @@
---
parent: Using BRouter
nav_order: 1
---
# Android quickstart guide
### Choosing and installing a map tool
BRouter just calculates tracks as GPX or GeoJSON files. It does not display maps
or give any navigation instuctions. Therefore you need a map-tool in order for
BRouter to be useful.
Several map tools support routing with BRouter:
- [_OsmAnd_](http://www.osmand.net): GPLv3, Free (limited features) and paid version available
- [_Locus Map_](http://www.locusmap.eu): Proprietary, Free (ads) and paid version available
- [_Oruxmaps_](http://www.oruxmaps.com): Proprietary, Free (previous version) and paid version available
Install any of those map tools using your favorite app store.
### Installing BRouter
You can install BRouter either from
[F-Droid](https://f-droid.org/packages/btools.routingapp), [Google Play
Store](https://play.google.com/store/apps/details?id=btools.routingapp) or from
the APK contained in the releases available in the [Revision
History](https://brouter.de/brouter/revisions.html).
### Choosing a base directory
When first starting BRouter (or after deleting/moving the base directory), it
asks for a directory and gives you proposals plus the option to enter any other
base directory.
Most phones have an internal and an external storage, where the external storage
is a SD card which can be removed from the device.
Navigation needs big data files that usually should go on an external storage
because it provides larger capacity. You should accept the external storage,
which is usually the one with the most space available.
Since Android 11 apps can only write to their app-specific storage so BRouter
can only use `<...>/Android/media/btools.routingapp/` as base directory. The
app-specific storage can be located on internal or external storage.
On Android versions prior to 11 it is possible to read and write to other
locations which is used for the _file interface_. For the _service interface_
access to other apps app-specific storage isn't required.
### Download routing segments
BRouter requires routing data which is independent of the displayed map of a map
tool. Routing segments (`rd5`) can be downloaded using the BRouter _Download
Manager_.
## Routing via _service interface_
BRouter is best used via it's _service interface_. It provides a service which
can be used by map tools without starting the BRouter app.
To use BRouter in your map tool you have to configure the map tool to use
BRouter as navigation service.
- [Instructions for LocusMap](https://docs.locusmap.eu/doku.php?id=manual:faq:how_to_navigate_offline)
- [Instructions for OsmAnd](https://osmand.net/features/navigation-profiles#create_brouter)
Note: OsmAnd only displays BRouter as navigation service if BRouter is
installed. You have to install BRouter before configuring OsmAnd.
The _service interface_ allows specifing either a _routing-mode_ (used by OsmAnd
and OruxMaps) or a _routing-profile_ (used by LocusMap). When using a
_routing-mode_ BRouter selects the _routing-profile_ according to a mapping.
By default BRouter uses the following mapping:
| routing-mode | routing-profile |
| -------------- | --------------- |
| motorcar_fast | car-test |
| motorcar_short | moped |
| bicycle_fast | fastbike |
| bicycle_short | trekking |
| foot_fast | shortest |
| foot_short | shortest |
This mapping, however, can be changed any time by starting the BRouter and using
the _Server Mode_.
If your routing request fails due to timeout you can open BRouter and select
_Server Mode_ and recalculate the route using _\<repeat:...\>_. BRouter caches
the routing result and further requests using the _same_ destination using the
_service interface_ will be successful.

23
docs/users/download_segments.md Normal file
View file

@ -0,0 +1,23 @@
---
parent: Using BRouter
---
# Download Routing Segments
Routing data files are organised as 5\*5 degree files, with the filename
containing the south-west corner of the square, which means:
- You want to route near West48/North37 -> you need `W50_N35.rd5`
- You want to route near East7/North47 -> you need `E5_N45.rd5`
These data files, called _segments_ across BRouter, are generated from
[OpenStreetMap](https://www.openstreetmap.org/) data and stored in a custom
binary format (rd5) for improved efficiency of BRouter routing.
## Download them from brouter.de
Segments files from the whole planet are generated weekly at
[https://brouter.de/brouter/segments4/](http://brouter.de/brouter/segments4/).
You can download one or more segments files, covering the area of the planet
your want to route, into the `segments4` directory.

30
docs/users/index.md
View file

@ -1,8 +1,10 @@
---
title: Using BRouter
has_children: true
nav_order: 3
---
# Using BRouter
## Online
Check [brouter-web](https://brouter.de/brouter-web/) or
@ -10,30 +12,8 @@ Check [brouter-web](https://brouter.de/brouter-web/) or
## BRouter on Android
You can install the BRouter app on your Android device from
[F-Droid](https://f-droid.org/packages/btools.routingapp) or [Google Play
Store](https://play.google.com/store/apps/details?id=btools.routingapp). Older
versions are available in the [revision history](../revisions.md). You can find
detailed documentation of the BRouter Android app in
[`misc/readmes/readme.txt`](misc/readmes/readme.txt).
### Android with Locus
You can use BRouter as the offline routing engine for [Locus
Map](https://www.locusmap.eu/) on your Android device. This is currently the
most featureful and maintained solutions for using BRouter on your Android
device.
A full documentation on how to set this up is available in the [LocusMap user
manual](https://docs.locusmap.eu/doku.php?id=manual:faq:how_to_navigate_offline).
### Android with OsmAnd
Alternatively, you can also use BRouter as the offline routing engine for
[OsmAnd](https://osmand.net/) on your Android device.
A full documentation on how to set this up is available in the [OsmAnd feature
description](https://osmand.net/features/navigation-profiles#create_brouter).
BRouter provides offline route calculation on Android. To get started with
BRouter on Android see the [Quickstart](android_quickstart.md).
## Google group for support questions and feedback