Improve documentation

* Improve documentation about BRouter usage and the provided scripts
(misc/scripts).
* Document how to use BRouter with third-party apps on Android (Locus /
OSMAnd).
* Improved process_planet_pbf.sh map creation script to make use of
osmupdate if available and avoid downloading the planet file if not
needed.

README.md

@@ -1,40 +1,129 @@
 BRouter
 =======
 
-BRouter is a configurable OSM offline router with elevation awareness, Java + Android. Designed to be multi-modal with a particular emphasis on bicycle routing.
+BRouter is a configurable OSM offline router with elevation awareness, Java +
+Android. Designed to be multi-modal with a particular emphasis on bicycle
+and energy-based car routing.
 
-For more infos see http://brouter.de/brouter
+For more infos see [http://brouter.de/brouter](http://brouter.de/brouter).
+
+
+## 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). You
+can also [build BRouter](#build-and-install) yourself. You can find detailed
+documentation of the BRouter Android app in
+[`misc/readmes/readme.txt`](misc/readmes/readme.txt).
 
 <a href="https://f-droid.org/packages/btools.routingapp" target="_blank">
 <img src="https://f-droid.org/badge/get-it-on.png" alt="Get it on F-Droid" height="90"/></a>
 <a href="https://play.google.com/store/apps/details?id=btools.routingapp" target="_blank">
 <img src="https://play.google.com/intl/en_us/badges/images/generic/en-play-badge.png" alt="Get it on Google Play" height="90"/></a>
 
+### Android with Locus
 
-## Build and Install
+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.
 
-Compile with (Java 6!):
+A full documentation on how to set this up is available at
-
+[https://www.locusmap.eu/locus-map-can-navigate-offline/](https://www.locusmap.eu/locus-map-can-navigate-offline/).
-> mvn clean install -Dandroid.sdk.path=<your-sdk-path>
-
-To skip building for Android, add ``-pl '!brouter-routing-app'``.
-
-Next, download one or more [data file(s)](http://brouter.de/brouter/segments4/) (rd5) into the ``misc/segments4`` directory.
-
-## Run
-
-On Linux:
-> ./misc/scripts/standalone/server.sh
-
-On Windows (using Bash):
-> ./misc/scripts/standalone/server.sh
-
-On Windows (using CMD):
-> misc\scripts\standalone\server.cmd
 
 
-Related Projects
+### Android with OSMAnd
-================
 
-* https://github.com/nrenner/brouter-web
+Alternatively, you can also use BRouter as the offline routing engine for
-* https://github.com/poutnikl/Brouter-profiles/wiki
+[OSMAnd](https://osmand.net/) on your Android device.
+
+A full documentation on how to set this up is available at
+[`misc/readmes/osmand/README.md`](misc/readmes/osmand/README.md).
+
+
+## BRouter on Windows/Linux/Mac OS
+
+### Build and Install
+
+To compile BRouter (including the BRouter Android app), use
+
+```
+mvn clean install -Dandroid.sdk.path=<your-sdk-path>
+```
+
+If you only want to compile BRouter and the server part (skipping the Android
+app), use
+
+```
+mvn clean install -pl '!brouter-routing-app'
+```
+
+You can use `-Dmaven.javadoc.skip=true` to skip the JavaDoc processing and
+`-DskipTests` to skip running the unitary tests.
+
+
+### Get the required segments (data) files
+
+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
+[http://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 `misc/segments4` directory.
+
+#### Generate your own segments files
+
+You can also generate the segments files you need directly from a planet dump
+of OpenStreetMap data (or a [GeoFabrik extract](https://download.geofabrik.de/)).
+
+More documentation of this is available in the
+[`misc/readmes/mapcreation.md`](misc/readmes/mapcreation.md) file.
+
+
+### 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.
+
+
+## Documentation
+
+More documentation is available in the [`misc/readmes`](misc/readmes) folder.
+
+
+## Related Projects
+
+* [nrenner/BRouter-web](https://github.com/nrenner/brouter-web), a web interface on
+    top of the BRouter HTTP server. An online instance is available at
+    [http://brouter.de/brouter-web/](http://brouter.de/brouter-web/).
+* [poutnikl/Brouter-profiles](https://github.com/poutnikl/Brouter-profiles/wiki),
+    a collection of BRouter profiles.
+* [Phyks/BRouterTesting](https://github.com/Phyks/BrouterTesting), a
+    collection of test cases for helping develop new BRouter profiles.
+
+
+## License
+
+BRouter is released under an [MIT License](LICENSE).

misc/readmes/mapcreation.md

@@ -0,0 +1,81 @@
+Build your own BRouter segments files
+=====================================
+
+BRouter uses its own data format (`.rd5` files), split in tiles of 5 x 5
+in latitude and longitude. You can download the official segment files (weekly
+built) from [brouter.de](http://brouter.de/brouter/segments4/) but you can
+also build them yourself from an OSM dump.
+
+
+## Build the pbfparser
+
+First, there are two file formats available to download OSM data: `bzip`-ed
+XML files (very large) and `.pbf`
+([Protobuf](https://github.com/protocolbuffers/protobuf) format) which is much
+more efficient. If you want to use the latter one, you will have to build the
+`pbfparser` (located in `misc/pbfparser` first):
+
+* Download [the latest
+    version](https://bretth.dev.openstreetmap.org/osmosis-build/osmosis-latest.zip)
+    of [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and unzip it
+    somewhere.
+* Copy the `lib/default/protobuf-java-*.jar` and
+    `lib/default/osmosis-osm-binary-*.jar` files from the unzipped Osmosis
+    archive to `misc/pbfparser/protobuf.jar` and `misc/pbfparser/osmosis.jar`.
+* Build BRouter and copy
+    `brouter-server/target/brouter-server-*-jar-with-dependencies.jar` to
+    `misc/pbfparser/brouter.jar`.
+* You can build the `pbfparser` using, in the `misc/pbfparser/`
+    folder,
+
+```
+javac -d . -cp "brouter.jar:protobuf.jar:osmosis.jar" *.java
+```
+
+* Finally, you can build a `jar` file from these files using
+
+```
+jar cf pbfparser.jar btools/**/*.class
+```
+
+_Note:_ If the `jar` file is not properly created, everything else will seem
+to work normally but there will not be any data extracted from the OSM data
+dump. You can check what is actually inside the built `jar` file using
+`jar tf pbfparser.jar`.
+
+
+## Run the map creation script
+
+If you want to have elevation information in the generated segments files, you
+should download the required [SRTM
+files](https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/)
+and set the `SRTM_PATH` variable when running the `process_pbf_planet.sh`
+script.
+
+Any flavor of the 90m SRTM database should be working, but the one used by the
+official BRouter segments files are the ones provided by
+[CGIAR](https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/).
+If you are working with rather small geographical extracts, you can download
+tiles manually using [this
+interface](http://srtm.csi.cgiar.org/SELECTION/inputCoord.asp) (use the
+"ArcInfo ASCII" format), instead of having to ask for an access for bulk
+download of data. There is no need to unzip the downloaded files, the
+`process_pbf_planet.sh` script expects a folder with all the ZIP files inside
+and will manage it.
+
+Note that if you don't have the SRTM data available, the segments files will
+still be generated without any issue (but they will miss the elevation data).
+If you are not sure which SRTM files you have to download, you can run the
+script once and it will log all the SRTM files it is looking for.
+
+You can now run the `misc/scripts/mapcreation/process_pbf_planet.sh` script to
+build the segments. Have a look at the variables defined at the beginning of
+the files and overwrite them according to your needs. By default, the script
+will download the latest full planet dump from
+[planet.osm.org](https://planet.osm.org/). You can also download a
+geographical extract provided by [Geofabrik](https://download.geofabrik.de/)
+and set the `PLANET_FILE` variable to point to it.
+
+_Note:_ It is possible that you encounter an error complaining about not being
+able to run `bash^M` on Linux/Mac OS. You can fix this one by running
+`sed -i -e 's/\r$//' process_pbf_planet.sh`.

misc/readmes/osmand/README.md

@@ -0,0 +1,64 @@
+Using BRouter on Android with OSMAnd
+====================================
+
+BRouter integration in OSMAnd changed a lot during the summer of 2019. This
+guide assumes you are using the BRouter Android app in version 1.5.0 or higher
+as well as OSMAnd in version 3.4 or higher.
+
+
+## Installing BRouter app on your Android device
+
+First, 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). You
+can also build the BRouter Android app yourself.
+
+<a href="https://f-droid.org/packages/btools.routingapp" target="_blank">
+<img src="https://f-droid.org/badge/get-it-on.png" alt="Get it on F-Droid" height="90"/></a>
+<a href="https://play.google.com/store/apps/details?id=btools.routingapp" target="_blank">
+<img src="https://play.google.com/intl/en_us/badges/images/generic/en-play-badge.png" alt="Get it on Google Play" height="90"/></a>
+
+
+## Downloading BRouter segments
+
+Then, launch the BRouter app and choose "Download Manager". Zoom in and select
+the areas you want to route in. Then click "Start Download" and BRouter will
+start downloading the [segments](http://brouter.de/brouter/segments4/) files
+for the selected areas.
+
+<img src="./brouter-main.png" alt="Main menu of BRouter android app"/>
+
+<img src="./brouter-grid.png" alt="Grid selection of segments to download"/>
+
+Note that you will have to repeat this step periodically, whenever you want to have an
+updated version of the OSM data used for the routing.
+
+
+## Selecting profiles to use
+
+Once this is done, start again the BRouter app and choose the "BRouter App"
+entry on the main menu. Select the routing profile you want to use and click
+"Server-Mode". Then, tick the boxes for the routing modes you want to use this
+profile for. You can use two different profiles per transportation mode, which
+will be mapped to the "shortest" and "fastest" presets (these are just
+labelling) in OSMAnd.
+
+<img src="./brouter-profiles.png" alt="Profiles selection"/>
+
+<img src="./brouter-profiles-summary.png" alt="Profiles selection summary"/>
+
+
+## Configure OSMAnd to make use of BRouter offline navigation
+
+You can now create an "Application profile" in OSMAnd which will be using
+BRouter for offline routing. Go to Settings -> Application profiles -> Add and
+create a new profile based on the base profile of your choice (cycling here,
+for bicycle routing), with a custom name of your choice ("BRouter" on the
+screenshot below) and making use of "BRouter (offline)" for navigation.
+
+<img src="./brouter-osmand.png" alt="BRouter configuration in OSMAnd
+application profiles"/>
+
+The BRouter app should be launched before OSMAnd for this specific entry to
+appear in OSMAnd. Therefore, if you cannot find "BRouter (offline)" navigation
+option, you should force quit OSMAnd and restart it.

misc/scripts/mapcreation/process_pbf_planet.sh

@@ -1,6 +1,19 @@
 #!/bin/bash
 set -e
-wget -N http://planet.openstreetmap.org/pbf/planet-latest.osm.pbf
+cd "$(dirname "$0")"
+
+# Fetch OSM planet dump if no planet file is specified
+if [ -z "$PLANET_FILE" ]; then
+    if [ -x "$(command -v osmupdate)" ] && [[ -f "./planet-latest.osm.pbf" ]]; then
+        # Prefer running osmupdate to update the planet file if available
+        mv "./planet-latest.osm.pbf" "./planet-latest.old.osm.pbf"
+        osmupdate "planet-latest.old.osm.pbf" "./planet-latest.osm.pbf"
+        rm "./planet-latest.old.osm.pbf"
+    else
+        # Otherwise, download it again
+        wget -N http://planet.openstreetmap.org/pbf/planet-latest.osm.pbf
+    fi
+fi
 
 if test lastmaprun.date -nt planet-latest.osm.pbf; then
    echo "no osm update, exiting"
@@ -20,7 +33,7 @@ OSMOSIS_JAR=$(realpath "../../pbfparser/osmosis.jar")
 PROTOBUF_JAR=$(realpath "../../pbfparser/protobuf.jar")
 PBFPARSER_JAR=$(realpath "../../pbfparser/pbfparser.jar")
 
-PLANET_FILE=$(realpath "./planet-latest.osm.pbf")
+PLANET_FILE=${PLANET_FILE:-$(realpath "./planet-latest.osm.pbf")}
 # Download SRTM zip files from
 # https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/
 # (use the "ArcInfo ASCII" version) and put the ZIP files directly in this