reworked readme for 0.9.9

misc/readmes/readme.txt

@@ -1,4 +1,4 @@
-BRouter - Beta Version 0.9.8 - Setting up the Android App
+BRouter - Beta Version 0.9.9 - Setting up the Android App
 =========================================================
 
 Choosing and Installing a Map-Tool
@@ -16,7 +16,6 @@ at least one of them:
 - "OsmAnd": See http://www.osmand.net Get It from Google-Play
    or get it as an APK from the release-build archive:
    http://download.osmand.net/releases/
-   I tested versions up to 1.6
 
 - "Locus": See http://www.locusmap.eu There's a "Pro"
   Version which is ad-free and a free version with ads. 
@@ -30,29 +29,58 @@ at least one of them:
 Which one to use is a matter of taste. Maybe OsmAnd is
 more plug&play and has a reasonable voice-guidig. Locus
 and Oruxmaps are more powerful and better for outdoor
-use. Locus for example has elevation profile diagrams
+use. Locus and Oruxmaps have elevation profile diagrams
 which OsmAnd has not.
 
 Locus and Oruxmaps are best used with third-party vector
 maps, check http://www.openandromaps.org if you consider
 to go for Locus or OruxMaps.
 
+Installing the BRouter App
+--------------------------
 
-Choosing an SD-Card Base Directory
+You can install the BRouter-App either from Google's Play Store
-----------------------------------
+or directly from the APK-File contained within the "brouter_0_9_9.zip"
+distribution zip-file.
 
-Some phones (namely those with Android 4.x) have 2 logical
+Both APKs are not identical: While the Google-Play-Version contains
+a download manager and asks for internet access, the APK from the
+distribution zip is the "pure offline" version and does not contain
+the download manager. The download manager assists downloading the
+required routing data files. If you are using the pure-offline version,
+it's on you to download these files manually. Or you can start with
+the Google-Play version and later on install the pure offline APK,
+replacing the other one, thus disabling internet access (Un-Installing
+BRouter does not delete anything on the sd-card).
+
+The pure-offline APK  asks for permissions to access the SD-Card
+and to de-activate the screen saver, but not for internet access.
+
+
+Choosing a SD-Card Base Directory
+---------------------------------
+
+When first starting BRouter (or after deleting/moving
+the brouter folder on the sd-card), it asks for a
+sd-card base directory and gives you proposals plus
+the option to enter any other base directory.
+
+Most phones (namely those with Android 4.x) have 2 logical
 "SD-Cards", where the first one is internal and not an actual
 Card, and the second one is a an optional "external" micro-sd-card
 that can be taken out of the device.
 
-If you have such a setup, try to make sure your map-tool uses
+Navigation needs big data files that usually should go on an
-the external sd-card to store the offline maps and other stuff.
+external, big sd-card. You should accept the external card, which
+is usually the one with the most space available.
 
-In OsmAnd, this works by choosing an "SD-Card base directory". Typically,
+Try to make sure your map-tool uses the same base directory
-the first card in mounted on "/mnt/sdcard", while the external
+to store the offline maps and other stuff, because BRouter
-one maybe mounted at "/mnt/sdcard/external_sd", but depending
+tries to access the maptool's waypoint-database and tracks-directory,
-on your phone it can be some other path.
+and this works only if they use either the same base directory
+or if the maptool uses the standard, internal base /mnt/sdcard.
+
+In OsmAnd, this works by choosing an "SD-Card base directory".
 
 In OruxMaps, path configuration is only possible for the actual
 map data, but the configuration database file that BRouter tries
@@ -64,91 +92,19 @@ The first line of that redirection file called "brouter.redirect"
 must contain the absolute path of the directory where you want
 the gpx-files to go (e.g. /storage0/oruxmaps/tracklogs).
 
-Make sure you understand the concept of the SD-Card base-directory,
-because the communication between BRouter and the Map-Tools
-requires that both are using either the same base-directory,
-or the maptools are using the standard base directory (/mnt/sdcard).
 
+Completing your installation
+----------------------------
 
-Selecting Waypoints in your Maptool
+After accepting a base-directory proposal, "BRouter" creates a subfolders
------------------------------------
+relative to this base directory, so you end up with e.g. the following structure:
-
-In order to calculate a route, BRouter needs to know
-at least a starting point and an endpoint. You specify
-them by creating waypoints in your map-tool.
-
-These are called "Favorites" in OsmAnd, "POI"s in Locus
-or "Wayoints" in Oruxmaps and allow to store a location
-on the map and give it a name.
-
-Pleae specify at least a waypoint called "from" for
-the starting-point and another called "to" for the
-endpoint (lowercase! names are case-sensitive) You
-can use any category, as only the name is read by BRouter.
-
-Optionally, you can specify more waypoints:
-
- "via1" ... "via9" to specify stop-overs
-
- "nogo[radius] [name]" to specify 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
-  nogo-waypoints.
-
-Make sure to not create duplicates for the from, to and via-waypoints,
-as BRouter would complain about duplicates. For nogo-areas,
-duplicates are allowed.
-
-Starting from version 0.97, instead of following the from/to/via
-naming convention, you can choose any names and select them from
-withing BRouter.
-
-
-Installing the BRouter App
---------------------------
-
-Download the file "brouter_0_8.zip" and unpack in a directory
-"brouter" on the SD-Card of your Android Device. Most convenient
-is to attach the device (or just the sd-card) to a desktop-computer
-and do the unpacking there, but doing that on the device itself
-is also possible, provided you know the appropriate tools.
-
-Install the BRouter-App by installing the APK-File "BRouter.apk"
-For instructions how to install from an APK (in contrast to
-installing from Google Play), search the internet for tips.
-You may need to change system configuration, some setting like
-"Applications->Unknown sources" depending on Android version.
-
-The BRouter App asks for permissions to access the SD-Card
-and to de-activate the screen saver. Being an offline app,
-it does NOT ask for internet access. The drawback is that
-you have to install the additional resources manually.
-
-
-BRouter's SD-Card Directory Structure
--------------------------------------
-
-BRouter guesses a reasonable sd-card base directory and on
-first start prompts you for a base directory with it's
-guess as a default. You should choose the same base
-directory that is used by your map-tool.
-
-On first start, BRouter will create a "brouter" subdirectory
-relative to that base-directory if it's not already there
-(becaused you created it by unpacking the zip-file, see above)
-
-If later on you want to change the base directory, you can delete
-or rename the 'brouter' subfolder, so it will prompt again for
-a base directory. You should choose the same base directory that
-is used by your map-tool (OsmAnd or Locus).
-
-So you may end up with e.g. the following directory structure
 (depending on base dir and your map-tool choice):
 
 /mnt/sdcard/brouter
-/mnt/sdcard/brouter/segments2  <- put routing data files (*.rd5) here
+/mnt/sdcard/brouter/segments2            <- ** put routing data files (*.rd5) here **
-/mnt/sdcard/brouter/profiles2  <- put lookup-table and routing profiles here
+/mnt/sdcard/brouter/segments2/carsubset  <- ** put *.cd5 files here **
+/mnt/sdcard/brouter/profiles2  <- lookup-table and routing profiles
+/mnt/sdcard/brouter/modes      <- routing-mode/profile mapping
 
 /mnt/sdcard/osmand             <- OsmAnd's sd-card dir
 /mnt/sdcard/osmand/track       <- OsmAnd's track storage
@@ -159,10 +115,29 @@ So you may end up with e.g. the following directory structure
 /mnt/sdcard/oruxmaps           <- Oruxmaps's sd-card dir
 /mnt/sdcard/oruxmaps/tracklogs <- Oruxmaps's track storage
 
-Starting with version 0.94, if a non-standard base directory
+
-is choosen (e.g. /mnt/sdcard/external_sd) BRouter tries to
+The "profiles2" and the "modes" directory get some reasonable default-configuration
-additionally to access the configuraion files relative
+from the installation procedure, but the "segments2" directory is still empty, so
-to the standard base directory ( /mnt/sdcard )
+you have to get routing-datafiles in order to complete your installation.
+
+If using the Google-Play version, the download manager starts automatically to
+help you with this download. If using the pure offline APK, you can download
+them manually from the following locations:
+
+  http://h2096617.stratoserver.net/brouter/segments2
+  http://h2096617.stratoserver.net/brouter/segments2/carsubset
+
+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 -> get W50_N35.rd5
+- You want to route near East7/North47 -> get E5_N45.rd5
+
+From the above link you find routing data for all places in the world where OSM
+data is available. The carsubset datafiles are needed only if you want to
+calculate car-routes ovefr lomg distances, otherwise you are fine with just the
+normal (full) rd5's.
 
 The minimum files BRouter needs to work are e.g.
 
@@ -173,45 +148,107 @@ The minimum files BRouter needs to work are e.g.
 But of course you can put as many routing data files
 and routing profiles as you like.
 
-Get the profiles (*.brf) and the lookup.dat from
-the zip-file or from:
 
-  http://www.dr-brenschede.de/brouter/profiles2
+Routing via the service interface
+=================================
 
-And the routing data files from:
+BRouter is best used via it's "service interface". No need to start the BRouter-App
+in order to do that, it's just a services that sits in the background and can be
+called by the map-tools very much like on online routing service.
 
-  http://h2096617.stratoserver.net/brouter/segments2
+To do that, you have to choose BRouter as a navigation service in your map-tool.
+This is supported by OsmAnd, Locus-Maps and OruxMaps (In OsmAnd starting with version 1.7,
+you see BRouter is a navigation service if BRouter is installed. You do not see the
+option if BRouter is not installed).
 
-Routing data files are organised as 5*5 degree files,
+There's a mapping between the "routing-mode" asked for by the map-tool
-with the Filename containing the south-west corner
+(on out of 6: car/bike/foot * fast/slow) and BRouter's routing-profiles.
-of the square, which means:
+This mapping is stored in the file brouter/modes/serviceconfig.dat and is
+pre-configured by the installation process to the following mapping:
 
-- You want to route near West48/North37 -> get W50_N35.rd5
+  motorcar_fast  -> car-test
-- You want to route near East7/North47 -> get E5_N45.rd5
+  motorcar_short -> moped
+  bicycle_fast   -> fastbike
+  bicycle_short  -> trekking
+  foot_fast      -> shortest
+  foot_short     -> shortest
 
-From the above link you find routing data for all
+This mapping, however, can be changed any time by starting the BRouter-APP and using
-places in the world where OSM data is available.
+the "Server Mode" button (or by editing the serviceconfig.dat manually). You can also
+change gthe profiles themselves or create new ones. Please refer to the
+"profile_developers_guide.txt" (contained in the distribution-zip) if you plan to
+adapt routing profiles to your preferences.
 
-Starting the BRouter Android-APP
+Note that if called via the service-interface, BRouter uses a timeout of 60 seconds,
---------------------------------
+which sets a limit on the distances you can calculate.
 
-Make sure you selected "from" and "to" waypoints
-in your maptool as decsribed above.
 
-Then you can start BRouter. It will read the waypoints
+Calculate routes using the file interface
-from the map-tools database, calculate the route and
+=========================================
-store the result as "brouter0.gpx" in the map-tools
-track directory.
 
-BRouter shows a graphical animation of the routing
+The other option is using the BRouter-App to calculate a route. This is the prefered option
-algorithm, and shows some messages on distances
+when calculating long-distance-routes that would not finish within the 60 seconds timout
-and ascends. The "filtered ascend" is a measure
+if calculated via the service-interface.
-for the real hill-climbing pain, with small
-variations filtered out.
 
-Then you can use your maptool to view or navigate the
+To do this, start the BRouter-App, select two or more wayoints from the waypoint-database
-route.
+of your map-tool and then start the route calculation. These waypoints are called "Favorites"
+in OsmAnd, "POI"s in Locus or "Wayoints" in Oruxmaps and allow to store a location
+on the map and give it a name.
 
-If started once more with identical input,
+No need anymore to create special "to", "from", "via1..via9" points, but they are still supported
-BRouter will store a second route broute1.gpx
+and if a "from" and a "to" wayppoint is found in the database, you will not be prompted
+to select waypoints from the database.
+
+If a route is calculated, it is stored as "brouter0.gpx" in the map-tools track directory.
+If started once more with identical input, BRouter will store a second route broute1.gpx
 for the first alternative and so on.
+
+If more than one of the supported maptools is installed, BRouter chooses the way-point database
+with the most recent timestamp.
+
+
+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 does not touch the disc
+defined by the position and the radius of the nogo-area.
+
+Nogo-Areas are effective in the service-interface and in the BRouter-App.
+In the BRouter-App, 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 in 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
+personel routing preferences.
+
+
+Mixed operation: "timeout-free recalculations"
+==============================================
+
+You can combine both operation modes (service-interface + BRouter-App) 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 nd 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 destinatin 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.

misc/readmes/readme_car_subset.txt

@@ -1,47 +0,0 @@
-BRouter - Beta Version 0.9.5 - Using the car-subset datafiles
-==========================================================
-
-Starting with version 0.9.5, BRouter supports car-subset
-datafiles as a workaround for the memory issue in car routing.
-
-Car-routing, however, is still considered experimental,
-mainly due to the fact that turn-restrictions are still
-not handled. 
-
-The cause of the memory overflow in long-distance car-routing
-is the fact that a large fraction of the ways is not allowed
-for cars and that the node-cache-pipe of brouter is not designed
-to handle that. So the car-subset datafiles (".cd5") are identical
-to the full datafiles (".rd5"), but do not contain the nodes
-and ways that are not accessible for cars.
-
-Using the car-subset datafiles, car-routing over longer
-distances is possible, and it it somewhat faster than using
-the full datafiles.
-
-The car subset datafiles must be stored in a subdirectory
-"carsubset" of the "segments2" directory, so a possible
-file-system structure looks like this:
-
-  brouter/segments2/E5_N45.rd5
-  brouter/segments2/carsubset/E5_N45.cd5
-
-You can download the cd5's from the corresponding URL
-just like the rd5's.
-
-Access to the car-subset datafiles is enabled
-by assigning the routing-profile variable:
-
-  assign   validForCars        1
-
-as it is done for the "car-test" profile. In that case,
-the router first checks for the car-subset file, and,
-if it does not exist, uses the full datafile. It is
-o.k. to just install the car-subset file without
-having the full datafile installed.
-
-If you want to use the car-subset datafile for bike-routing
-(because you don't have the full datafile or because you
-are using streets only anyhow and want better performance),
-just assign the "validForCars" variable in your biking
-profile as indicated above.

misc/readmes/readme_service.txt

@@ -1,72 +0,0 @@
-BRouter - Beta Version 0.9.5 - Using the service interface
-==========================================================
-
-Starting with version 0.9.3, BRouter contains a *NEW* service interface.
-
-The HTTP-Interface introduced in 0.9.1-0.9.2 was dropped
-
-The new service interface is an Android service that can be called
-from other apps. See the file IBRouterService.aidl for the
-interface definition.
-
-Following map-tools implement this interface:
-
-- OruxMaps starting with version 5.5.3
-- Locus in the current version
-- (for OsmAnd, pull-request is pending: https://github.com/osmandapp/Osmand/pull/537 )
-
-The service interface defines a default timeout of 60 seconds
-(if not modified by the caller), so you can only calculate
-medium distance routes via the service interface. For long
-distance calculations, you would run into the timeout, so
-you have to use BRouter's classical operation mode at least
-for an initial calculation. But read below on how timeout-free
-recalculations work even for long-distance applications.
-
-The configuration concept in the service interface
---------------------------------------------------
-
-BRouter is fully configurable via the use of profile
-definition files and a list of nogo-areas, while
-the service interface is usually accessed by just
-choosing one o the 6 "standard routing modes" made
-of a combination of the car/bike/foot and the
-shortest/fastest selection.
-
-Therefore, you need a mapping between the standard routing mode
-and BRouter's configuration. There is no default mapping
-deployed with the BRouter distribution file, so you have
-to configure this yourself. You can do that by starting
-BRouter is the "normal" way and at the end of the routing
-process, press the "Server Mode" button. Then you get
-a list of standard routing mode with a preselection,
-where you can choose for which of the 6 standard modes
-you want to store the configuration just used.
-(profile + nogo-list). Please note that the profile
-is stored by reference (so modifications at the profile
-file afterwards will have effect), while the nogo-areas
-are stored by value (so modifying the nogo-waypoints
-afterwards will have no effect)
-
-Timeout-free recalculations
----------------------------
-
-A new feature in zje service-interface of version 0.95 is that
-you can  follow a long-distance route and have (nearly) correct
-recalculations when getting of the track, without running
-into the 60-seconds timeout.
-
-For that, a valid route to the destination must be known
-for the current routing-mode. This can be achieved either
-by calculating the route via the brouter-app and storing
-it by pressing the "server-mode" button when done.
-
-Or it is done implicitly by the service-mode itself once
-it was able to do the calcultion within the timeout -
-in that case, subsequent recalcs for the same destination
-also make use of the known valid track for faster
-processing.
-
-The destination must be identical in a digital sense
-(+- 20 microdegrees), so make sure to use the same waypoint,
-do not re-enter it as a map-location.