Consolidate documentation / Update website

[zod]

We currently have information / documentation in several locations

• brouter.de has the original page as well as some top-level page
• The README.md in this repository contains links to the instructions for OsmAnd
• We have a readme.txt, readme_android11.txt and kitkat_survival_readme.txt

I think most users simply install the app from Google Play and won't find for example the OsmAnd instructions. It would be great if all the documentation was accessible in one location.

As a proof of concept I've created a GitHub Pages (made with Jekyll) site and imported some of the documentation (original website, profile developers guide and parts of README.md). Jekyll renders the site automatically from the markdown files and publishes it to https://zod.github.io/brouter/

It would be easier for starters if we would merge the information from readme.txt, readme_android11.txt and kitkat_survival_readme.txt into a single markdown document and provide it as html document.

Let me know what you think :)

[afischerdev]

Great idea. Should a part of new Android UI too - as link.

[abrensch]

I like that. Layout looks good, and having all the docs maintained in github would be good.

Structure should better guide "normal" users to the essential info and better hide technical stuff and outdated doku, but I think that will solve itself as soon as the deployment procedure is established.

regards, Arndt

[zod]

I've updated the documentation and split it into smaller parts.

Instead of adding another site it would be great to host this page on brouter.de and replace the existing site. There are two three ways to achieve it.

• Use GitHub pages and add brouter.de as a Custom Domain.

  Since brouter.de provides brouter-web, segment downloads, etc this seems rather complicated. Perhaps it could be solved using a subdomain for the documentation.

• Deploy to brouter.de server using GitHub Actions

  Jekyll builds a static site which can be hosted anywhere. We could adapt the workflow to either deploy to brouter.de using e.g. SSH or upload the artifact and add a script on brouter.de which pulls the artifact.

• Use GitHub pages and use brouter.de server as reverse proxy to serve the site.

  This allows defining the mapping which pages should be served from GitHub pages and which should be provided by brouter.de server (e.g. segment downloads)

[hamsterclassic]

It would be nice, if you could add a comment, what's the difference between -api19- and -api30-...apk I prefer downloading the zip from brouter.de and there's no explanation.

[areynoua]

I take advantage of this discussion to share this observation: as an intermittent user with a technical background but little time (and no knowledge of German), I really like BRouter for the possibility of creating profiles but I regret I never found some information like the parameters used to influence the kinematic model. Thanking you for the great work.

[polyscias]

I really like BRouter for the possibility of creating profiles but I regret I never found some information like the parameters used to influence the kinematic model.

Just opening up the (default) trekking.brf profile file gives the parameters:

# Kinematic model parameters (travel time computation)
assign totalMass  = 90     # %totalMass% | Mass (in kg) of the bike + biker, for travel time computation | number
assign maxSpeed   = 45     # %maxSpeed% | Absolute maximum speed (in km/h), for travel time computation | number
assign S_C_x      = 0.225  # %S_C_x% | Drag coefficient times the reference area (in m^2), for travel time computation | number
assign C_r        = 0.01   # %C_r% | Rolling resistance coefficient (dimensionless), for travel time computation | number
assign bikerPower = 100    # %bikerPower% | Average power (in W) provided by the biker, for travel time computation | number

totalMass is the total weight of the bike, rider and luggage. It is used:

1. when climbing/descending, more weight means more energy to go up
2. As factor in the rolling resistance, see below, C_r.

maxSpeed is used as speed limit. a normal e-bike is often limited to 25 km/h and a speed pedelec to 45 km/h.

_S_Cx, Drag coefficient times the reference area (in m^2) For this, you should know the drag force can be calculated using the Drag equation

So the drag force (Fd) is something times the speed/velocity squared (v²), this _S_Cx is that something so Fd = _S_Cx * v².

On the Internet you can find numbers for CdA, you have to multiply these numbers by ½ ρ and with ρ being about 1.2 that means times 0.6. The 0.225 default means CdA is 0,375 which corresponds to a racing bike. For a typical trekking bike I think CdA = 0.45 would be better, so S_C_x = 0.27

_C_r_ is the Rolling resistance coefficient. The rolling friction Froll = C_r totalMass 9,81. The default 0.01 seems to be on the high side for bicycles, see Rolling resistance coefficient examples.

bikerPower is how much power the cyclist delivers, 100 Watt is something normal fit people can sustain for > 1 hour.

For further details, have a look at Drag Force Formulas and have a look in the source, StdPath.java#L230

[polyscias]

what's the difference between -api19- and -api30-...apk

See https://developer.android.com/studio/releases/platforms, api19 means supported by Andriod 4.4 and later, api30 means supported by Andriod 11 and later.

[zod]

what's the difference between -api19- and -api30-...apk

See https://developer.android.com/studio/releases/platforms, api19 means supported by Andriod 4.4 and later, api30 means supported by Andriod 11 and later.

Both versions run on Android ICS (API14) and beyond, they target different android versions. I've added an explanation in #411.

[zod]

@abrensch I'd like to go forward with this, but I'm blocked because there are two deployment options (see https://github.com/abrensch/brouter/issues/373#issuecomment-1002446172) which could be used. What's your preferred way?

[zod]

I've updated the deployment options with a third option which could be used.

[zod]

I've tried the deployment using a reverse proxy with nginx locally and it seems to work fine and requires the least effort. To provide it at brouter.de we would require

• Enabling GitHub pages for this repository and slightly adapt the jekyll configuration
• Adapt server configuration on brouter.de

@abrensch I'm lacking permissions for both tasks. Are you the only one who could fix it or is there anyone else?