diff --git a/docs/developers/android_service.md b/docs/developers/android_service.md new file mode 100644 index 0000000..f9165a5 --- /dev/null +++ b/docs/developers/android_service.md @@ -0,0 +1,10 @@ +--- +parent: Developers +--- + +# Android Service + +BRouter exposes an [Android +Service](https://developer.android.com/guide/components/services) which can be +used by other applications to calculate routes. See `IBRouterService.aidl` for +the interface definition. diff --git a/docs/developers/build_segments.md b/docs/developers/build_segments.md index 2eafebf..604d8eb 100644 --- a/docs/developers/build_segments.md +++ b/docs/developers/build_segments.md @@ -1,5 +1,6 @@ --- parent: Developers +title: Build segment files --- Build your own segments files diff --git a/docs/developers/http_server.md b/docs/developers/http_server.md new file mode 100644 index 0000000..d00e454 --- /dev/null +++ b/docs/developers/http_server.md @@ -0,0 +1,16 @@ +--- +parent: Developers +title: HTTP server +--- + +# Run the BRouter HTTP server + +Helpers scripts are provided in `misc/scripts/standalone` to quickly spawn a +BRouter HTTP server for various platforms. + +* Linux/Mac OS: `./misc/scripts/standalone/server.sh` +* Windows (using Bash): `./misc/scripts/standalone/server.sh` +* Windows (using CMD): `misc\scripts\standalone\server.cmd` + +The API endpoints exposed by this HTTP server are documented in the +`ServerHandler.java` diff --git a/docs/developers/index.md b/docs/developers/index.md index 47430eb..e5c4304 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -22,24 +22,3 @@ variables in the first `global` context of the profiles files. An helper script is available in `misc/scripts/generate_profile_variants.sh` to help you quickly generate variants based on the default profiles, to create a default set of profiles covering most of the basic use cases. - -## Run the BRouter HTTP server - -Helpers scripts are provided in `misc/scripts/standalone` to quickly spawn a -BRouter HTTP server for various platforms. - -* Linux/Mac OS: `./misc/scripts/standalone/server.sh` -* Windows (using Bash): `./misc/scripts/standalone/server.sh` -* Windows (using CMD): `misc\scripts\standalone\server.cmd` - -The API endpoints exposed by this HTTP server are documented in the -[`brouter-server/src/main/java/btools/server/request/ServerHandler.java`](brouter-server/src/main/java/btools/server/request/ServerHandler.java) -file. - -## Android Service - -BRouter exposes an [Android -Service](https://developer.android.com/guide/components/services) which can be -used by other applications to calculate routes. See -[`brouter-routing-app/src/main/aidl/btools/routingapp/IBRouterService.aidl`](brouter-routing-app/src/main/aidl/btools/routingapp/IBRouterService.aidl) -for the interface definition. diff --git a/docs/features/elevation.md b/docs/features/elevation.md index 257ce95..453adc8 100644 --- a/docs/features/elevation.md +++ b/docs/features/elevation.md @@ -2,7 +2,7 @@ parent: Features --- -## Elevation algorithm +## Elevation awareness Elevation awareness is the most important issue in bike routing if not routing in a flat country. But in most routing software, elevation is either not handled diff --git a/docs/features/offline.md b/docs/features/offline.md index 519b07a..56f6837 100644 --- a/docs/features/offline.md +++ b/docs/features/offline.md @@ -27,31 +27,3 @@ developers to implement simplifications into the routing algorithm that affect the quality of the routing results. BRouter always does it's best on the quality, but has a processing time that scales quadratic with distance, leading to a limit at about 150km in air-distance, which is enough for a bikers daytrip. - -### Installing the BETA Version of BRouter on an Android smartphone. - -Before trying the Android app, you should have a look one the [online -version](/brouter-web) to see what it's doing. - -What you should also do before trying the BRouter Android app is to install, an -get familiar with, one of the supported map-apps. This is either -[OsmAnd](http://www.osmand.net), which is a full offline navigation solution on -it's own, but especially it's a wonderful offline OSM map tool and is able to -give spoken directions to routes calculated either internally or externally. -Other options are [Locus](http://www.locusmap.eu/) or -[OruxMaps](http://www.oruxmaps.com/index_en.html). - -The BRouter Android app assumes that at least one of OsmAnd, Locus or OruxMaps -is installed - it will not work otherwise. - -If you are o.k. with all that, you can install the BRouter Android app from the -[brouter_1_6_1.zip](../brouter_bin/brouter_1_6_1.zip) installation ZIP-file -including the APK and read the [readme.txt](readme.txt) ( **READ ME !** ) for -details on how to add routing data and navigation profiles to your installation -and how the interfacing between BRouter and the supported map-tools works. - -Navigation profiles and the lookup-data are [here](profiles2) Routing data files -per 5*5-degree square are [here](/brouter/segments4) - -(The Map-Snapshot date is about 2 days before the timestamp of the routing data -files) diff --git a/docs/features/vianogo.md b/docs/features/vianogo.md index 6899a13..dc95526 100644 --- a/docs/features/vianogo.md +++ b/docs/features/vianogo.md @@ -7,17 +7,10 @@ parent: Features BRouter can process via-points and nogo-areas, and [brouter-web](/brouter-web) offers on online interface to edit both of them. -For offline use, nogo-areas can be defined as wayoints using a special naming -convention. Handling of via-points during offline use depends on the mode of -operation, see the README for details. - -NoGo-Areas are forbidden areas. In fact, these are areas, not points, with a -default radius of 20m around the given point. Every way that is touching this -disc of 20m radius is excluded by the routing algorithm. But the radius can also -be specified: a waypoint `nogo` default to 20m radius, but `nogo100` defines a -nogo area with 100m radius. Theres no limit in radius, so you can also exclude a -whole geographic region with a single nogo-area. - Nogo areas are useful if you encouter an obstacle that is not contained in the underlying map. But they can also be useful in planning alternative routes by excluding e.g. a certain bridge or ferry. + +For offline use, nogo-areas can be defined as wayoints using a special naming +convention. Handling of via-points during offline use depends on the mode of +operation, see the README for details. diff --git a/docs/index.md b/docs/index.md index 0e4477f..90a79b2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ title: Home nav_order: 1 --- -## BRouter: Let's get serious about bike routing +# BRouter: Let's get serious about bike routing There's a lot of routing software on the market, both free and commercial, both online and offline, both OSM and proprietary maps. However, when it comes to @@ -20,17 +20,12 @@ result. Here's what makes BRouter unique: - It uses [freely configurable routing profiles](features/costfunctions.md) - - It works [fully offline on any Android phone](features/offline.md) and is interfaced to some of the most popular Android map tools - - It uses a sophisticated [routing-algorithm](developers/algorithm.md) with [elevation consideration](features/elevation.md) - - It offers [alternative route calculations](features/alternatives.md) - - It supports [via and nogo-points](features/vianogo.md) - - It can [consider long distance cycle routes](features/cycleroutes.md) Routing data is available worldwide with automatic weekly updates @@ -49,7 +44,7 @@ if you want to use BRouter online. ### Android app for offline routing -See [offline routing app](features/offline.md) for how to setup BRouter for +See [Android quickstart guide](users/android_quickstart.md) for how to setup BRouter for offline routing on an Android smartphone. ### Revision history diff --git a/docs/users/android_advanced.md b/docs/users/android_advanced.md new file mode 100644 index 0000000..c6b81c0 --- /dev/null +++ b/docs/users/android_advanced.md @@ -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 | +| --------------------------------- | -------------------------------------------- | +| `/brouter` | | +| `/brouter/modes` | routing-mode/profile mapping and route cache | +| `/brouter/profiles2` | lookup-table and routing-profiles (\*.brf) | +| `/brouter/segments4` | **routing data files (\*.rd5)** | +| `/brouter/import` | allow a small file exchange with other apps | +| `/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 +`/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. diff --git a/docs/users/android_quickstart.md b/docs/users/android_quickstart.md new file mode 100644 index 0000000..cfd64cb --- /dev/null +++ b/docs/users/android_quickstart.md @@ -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 _\_. BRouter caches +the routing result and further requests using the _same_ destination using the +_service interface_ will be successful. diff --git a/docs/users/download_segments.md b/docs/users/download_segments.md new file mode 100644 index 0000000..aba5475 --- /dev/null +++ b/docs/users/download_segments.md @@ -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. diff --git a/docs/users/index.md b/docs/users/index.md index e75a08a..3a80abd 100644 --- a/docs/users/index.md +++ b/docs/users/index.md @@ -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