From 2b70d8a862fd3d058d70a09bdd1bddbaa9de3c68 Mon Sep 17 00:00:00 2001 From: Arndt Date: Sun, 20 Apr 2014 14:55:10 +0200 Subject: [PATCH] reworked readme for 0.9.9 --- misc/readmes/readme.txt | 287 ++++++++++++++++------------- misc/readmes/readme_car_subset.txt | 47 ----- misc/readmes/readme_service.txt | 72 -------- 3 files changed, 162 insertions(+), 244 deletions(-) delete mode 100644 misc/readmes/readme_car_subset.txt delete mode 100644 misc/readmes/readme_service.txt diff --git a/misc/readmes/readme.txt b/misc/readmes/readme.txt index f2d4b35..be88572 100644 --- a/misc/readmes/readme.txt +++ b/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 -the external sd-card to store the offline maps and other stuff. +Navigation needs big data files that usually should go on an +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, -the first card in mounted on "/mnt/sdcard", while the external -one maybe mounted at "/mnt/sdcard/external_sd", but depending -on your phone it can be some other path. +Try to make sure your map-tool uses the same base directory +to store the offline maps and other stuff, because BRouter +tries to access the maptool's waypoint-database and tracks-directory, +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 ------------------------------------ - -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 +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: (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/profiles2 <- put lookup-table and routing profiles here +/mnt/sdcard/brouter/segments2 <- ** put routing data files (*.rd5) 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 -additionally to access the configuraion files relative -to the standard base directory ( /mnt/sdcard ) + +The "profiles2" and the "modes" directory get some reasonable default-configuration +from the installation procedure, but the "segments2" directory is still empty, so +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, -with the Filename containing the south-west corner -of the square, which means: +There's a mapping between the "routing-mode" asked for by the map-tool +(on out of 6: car/bike/foot * fast/slow) and BRouter's routing-profiles. +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 -- You want to route near East7/North47 -> get E5_N45.rd5 + motorcar_fast -> car-test + 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 -places in the world where OSM data is available. +This mapping, however, can be changed any time by starting the BRouter-APP and using +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 -from the map-tools database, calculate the route and -store the result as "brouter0.gpx" in the map-tools -track directory. +Calculate routes using the file interface +========================================= -BRouter shows a graphical animation of the routing -algorithm, and shows some messages on distances -and ascends. The "filtered ascend" is a measure -for the real hill-climbing pain, with small -variations filtered out. +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. -Then you can use your maptool to view or navigate the -route. +To do this, start the BRouter-App, select two or more wayoints from the waypoint-database +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, -BRouter will store a second route broute1.gpx +No need anymore to create special "to", "from", "via1..via9" points, but they are still supported +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. diff --git a/misc/readmes/readme_car_subset.txt b/misc/readmes/readme_car_subset.txt deleted file mode 100644 index 307a9a5..0000000 --- a/misc/readmes/readme_car_subset.txt +++ /dev/null @@ -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. diff --git a/misc/readmes/readme_service.txt b/misc/readmes/readme_service.txt deleted file mode 100644 index c148e70..0000000 --- a/misc/readmes/readme_service.txt +++ /dev/null @@ -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. \ No newline at end of file