Configuration (old)

From Navit's Wiki
Revision as of 13:29, 21 August 2008 by SlowRider (talk | contribs) (Graphical User Interface)
Jump to: navigation, search

Foreword

Setting up Navit is done by editing a configuration file. Unless specified, it is called "navit.xml". When launching, Navit will look for it in the following order:

  • The first argument supplied on the command line, e.g.: navit /home/myusername/navittestconfig.xml
  • The navit.xml file in ~/.navit/navit.xml : e.g : /home/myusername/.navit/navit.xml. This is probably to best place to customize your settings.
  • The navit.xml.local file in the current directory. Used mainly for development, but maybe also useful for you.
  • The navit.xml file in the current directory.

If you are working with a SVN checkout, you will find a preconfigured sample in navit/navit.xml. If you installed Navit via any installation software, it should have installed a global navit.xml somewhere on your system. In either case, make a copy of the file to one of the four locations mentioned above.

Now editing this file in a text editor is simple. It's just a plain text XML file. Any operating system provides a text editor, like TextEdit on Mac OS X, vi on Linux or Notepad on Windows.

Settings you might need to change

Starting position

You might want to change the starting position of navit, especially if you are using navit without a gps. You can get your coordinates here: http://itouchmap.com/latlong.html

You can change the starting position in navit.xml, here :

<navit gui="..." graphics="..." center="5031.51 N 735.83 E" zoom="128" >


Mapset

You probably need to change the mapset settings to display your map, or navit will use the default map of Munich.

Vehicle

This is where you will define your gps data source. You can use one of the following:

  • source="gpsd://localhost" : the default one, will try to connect to gpsd on localhost
  • source="file://dev/ttyS0" : in this example, we try to access the nmea directly on the serial port
  • source="file://mynmea.log" : here, navit will replay the nmea logfile mynmea.log
  • source="demo://" : to use the demo vehicle. Useful if you have no nmea data source.

Graphical User Interface

GUI:GTK

  • menubar="0" will disable the menu bar. Useful on devices with small screens
  • toolbar="0" will disable the tool bar. Useful on devices with small screens
  • statusbar="0" will disable the status bar. Useful on devices with small screens

GUI:CEGUI

  • skin="skin_name" will use the skin named skin_name instead of the default one, Taharez
  • fullscreen="1" will launch navit in fullscreen mode

A deeper look at the XML file

Structure

You can have a look at the navit.dtd file in the navit directory.


At the beginning, you will find the <plugins> section. This will be documented later. Leave it alone for now.

Next, you will have your navit instance.

An instance looks like the following :

  • A gui definition :
<navit [options]>
  • One or more vehicles to track (nmea data source, log file, etc)
<vehicle [options] />
  • A mapset, with one or more maps :
<mapset>
<map type="mg" enabled="yes" data="/opt/reiseplaner/travel/DE.map" />
<map type="mg" enabled="yes" data="/opt/reiseplaner/travel/DE.map/smp2.smp" />
</mapset>
  • And finally, one or more layouts.

Don't forget the </navit> at the end.

The navit instance

The default navit instance looks like this :

<navit center="5031.51 N 735.83 E" zoom="8192" >
<gui type="gtk" />
<graphics type="gtk_drawing_area" />


This will load the gtk gui, using the gtk_drawing_area graphics driver.

The center / zoom values are explained below also gui and graphics

The gui (gui)

Currently, navit has 3 guis :

  • the gtk gui (the default, good for desktop use)
  • the internal gui (under heavy development, mainly targeting mobile devices with touchscreens)
  • the cegui/opengl gui (must be used for 3D view. possibly broken)

If you're using the CEGUI gui, some tweaks are recommended. For the impatient :

  • Change the zoom level to 128 (the SDL renderer is designed to render close-to-ground maps)
  • Add follow="1" update="1" to your vehicle definition (to always center the view on your position, and to show what you should be seeing, instead of facing North)
  • tilt="400" view_mode="3D" to set initial view-mode and 3D-tilt.
  • media_window_title="TEST APP" media_cmd="test" to set action for the Media-button.
  • you can set the skin by using skin="skin name". Currently, navit is provided with 2 skins, the default one (Taharez) and the "Mineque" skin, which is still being worked on.

See below for more explanations.


The CEGUI gui seems currently not working on some platforms - this is investigated at the moment.

The graphic driver (graphics)

Also, the most used graphics drivers are the followings :

  • gtk_drawing_area, used by the gtk gui
  • sdl, usable with the internal gui. Can render inside an X window, or direct to the Linux framebuffer, without very many dependencies on external libraries.
  • opengl, used currently only by the cegui gui. This may change later, for example a GTK gui could use opengl to render its graphics.

The gtk gui looks like the following in the navit.xml:

<gui type="gtk" />
<graphics type="gtk_drawing_area" />

or for the internal gui (with gtk graphics):

<gui type="internal" />
<graphics type="gtk_drawing_area" />

or for the internal gui (with sdl graphics):

<gui type="internal" />
<graphics type="sdl" />

or for the cegui gui:

<gui type="cegui" tilt="400" view_mode="3D" skin="Mineque" />
<graphics type="opengl" />

For the moment don't attempt other gui / graphics combinations.

optional for gui_cegui a skin could be selected. It must be defined in the gui/cegui/datafiles directory

The default map view center (center)

This defines where the map should be centered at startup. Use WGS-84 coordinates.

The form is

center="[D]DMM.xxx N/S [D][D]DMM.yyy E/W"

or

center="[-][D]D.x[x]... [-][D][D]D.x[x]"

or

center="[-]0xX [-]0xX" 


D are degrees, M are minutes and xxx and yyy are the fractal parts of the minutes. Use N or S for North / South and E or W for East / West.

For example

center="4744.123 N 913.876 E"

The zoom level (zoom)

It's a power of 2 indicating the starting zoom level. 1 is the lower value, closest to the ground. You can use almost whatever power of two you want. Of course, the zoom level can be adjusted at run time :)

You can use almost any value for the gtk gui, but the sdl gui will react better (and the drawings will look nicer) with a lower zoom value. 128 is often a good idea for sdl :

<navit center="5031.51 N 735.83 E" zoom="128" >

The initial view (tilt, view_mode)

This defines the view mode the gui has on startup. "view_mode" can be set to '2D' or '3D'. The tilt value defines default camera tilting, with a value from 0 to 2000.

for example:

<gui type="cegui" tilt="400" view_mode="3D" />

The On Screen Display

See On Screen Display. Some quick examples:

   <osd type="compass" />
   <osd type="eta" />
   <osd type="navigation" />
   <osd type="button" x="632" y="516" command="zoom_in" src="osd_plus.png" />
   <osd type="button" x="716" y="516" command="zoom_out" src="osd_minus.png" />

The vehicles definitions

A vehicle definition looks like this :

<vehicle name="Meins" enabled="no" source="gpsd:\/\/localhost" color="#0000ff"/>

You can have as many vehicle as you like! It's for example usefull to track your friends, etc.

Source: If you don't want to use gpsd you can just type (the example is for a serial gps device)

<vehicle name="Meins" enabled="no" source="file://dev/ttyS0" color="#0000ff"/>

Here are the available options :

  • follow : this will force the map to be drawn with the bearing you currently have, instead of having the north at the top
  • update : this will force the map to be recentered at your main cursor's position.
  • color2 : Specify a second colour to display the cursor. The cursor will be drawn initially using 'color' then inlaid with 'color2'
  • animate : If set to 1, the cursor will be animated as a moving dotted line, to make it easier to see.
  • active : If set to 1, makes the vehicule the default active one. Routing and view centering would be applied to this one by default.

By default, in the gtk gui, the cursor moves onto the map until it reaches a border, then the map will be re-centered. This saves a lot of CPU time, by avoiding to always redraw the map (very useful for small devices like smart phones).

The 3d view of the SDL gui is meant to draw the road as YOU see it when driving, so you need to always recenter the map to your position. So, to get a good tracking, if you're using sdl, you should use this kind of settings :

<vehicle name="Meins" enabled="no" source="gpsd:\/\/localhost" color="#0000ff" update="1" follow="1"/>

[Currently trip recording does not work, you can use gpspipe to record your tracks, and gpsbabel to convert them to another format if necessary].

If you use gpspipe -r /tmp/log.nmea you can convert it to navit_txt. Save the following awk script to nmea2navit_txt.awk:

BEGIN { print "type=track" }

{
if ($1 == "$GPGGA" )
 {
 X=1
 HAS_POS=0
 while ( X <= NF)
  {
  if (($X == "N") || ($X == "E"))
   {
   HAS_POS=1
   printf $(X-1)" "$X" "
   }
  X=X+1
  }

 if ( HAS_POS == "1" )
  {
  print "type=trackpoint"
  }
 }
}

You can then convert your nmea logfile with:

cat /tmp/log.nmea | gawk -F"," -f nmea2navit_txt.awk > /tmp/log.txt

And use it in navit by adding:

<map type="textfile" enabled="yes" data="/tmp/log.txt"/>

to the vehicle section in your ~/.navit/navit.xml file.


To record your trip for Error Reporting: Add a sub-instance "log" to the vehicle

<log type="nmea" data="track_%Y%m%d%i.nmea" flush_size="1048576" flush_time="900" />

This will give a log file named YearMonthDaySequencenumber.nmea which will be kept in memory and flushed to disk when it is 1048576 bytes large or the oldest data is older than 900 seconds

<log type="gpx" data="track_%Y%m%d%i.gpx" flush_size="1048576" flush_time="900" />

Similar to above, but will produce a gpx log which is suitable for using it in josm instead of a nmea log,

<log type="textfile" data="track.txt" flush_size="0" overwrite="1" />

Will give you a tracklog usable as navit map, which is immediately written to disk and overwritten on navit restart

The mapset

Navit can read various map formats, and can even show multiple maps at a time. This is done by defining a mapset. Each mapset can have one or more maps. Using the GTK GUI, you can enable or disable specific maps at runtime.

Reiseplaner Maps

The following example is for the Reiseplaner maps :

<mapset>
  <map type="mg" enabled="yes" data="/opt/reiseplaner/travel/DE.map" />
  <map type="mg" enabled="yes" data="/opt/reiseplaner/travel/DE.map/smp2.smp" />
</mapset>

Here's some more informations about the maps of Reiseplaner :

  • DE.map is mandatory. This contains the towns and major roads of Europe
  • DE.map/smp2.smp contains the smaller roads for France
  • DE.map/smp3.smp contains the smaller roads for Germany

OpenStreetMap Maps

See OpenStreetMaps for details on how to create a map file that Navit can use from OpenStreetMap data. Once you have a suitable file, define a mapset using something like:

<mapset>
  <map type="binfile" enabled="yes" data="/var/navit/maps/uk.bin" />
  <map type="binfile" enabled="yes" data="/var/navit/maps/france.bin" />
</mapset>

Note that there are some limitations at present when using OSM data with Navit.



< (to be filled) >

Valid map types:

  • binfile
  • garmin
  • mg
  • poi_geodownload
  • textfile

The layout

The layout define a specific scheme of colored items, for example "Day" or "Night".

Notice : the items will be drawn on the map in the order they are defined in the layout. So the "Wood" layout will be drawn first, then the towns, then the street, and finally your track. You can change this order if you like, but remember that an item drawn on top of another may hide it.

Defining an item. An item is defined this way :

<item type="water_poly" zoom="0-">
<polygon color="#82c8ea" />
<polyline color="#5096b8" />
</item>

The zoom option tells navit from which scale the item should be drawn. It can be a single value, or a range. 0- will always draw the item (because the zoom can't be < 1 ) 0-5 will draw the item when the zoom value is < 6. Order goes from 0 (globally visible) to 18 (visible only on very close zoom)

The polygon color defines the color with which the polygon will be filled. Of course, it applies only to polygons, such as water, towns, wood, etc.

The polyline color define the color with which the lines will be drawn. If the item is a line, such as a street, it's its color. If the item is a polygon, then it is it's border color.

You can define an item multiple times. Example :

<item type="street_route" zoom="17">
<polyline color="#0000a0" width="268" />
</item>
<item type="street_route" zoom="18">
<polyline color="#0000a0" width="530" />
</item>

Here we define two different widths for the same item, depending on the scale. We could even have changed its color depending on the scale.

Support for XInclude/XPath

Navit has support for a small subset of XInclude/XPath. Supported is a tag like

<xi:include href="some_file" xpointer="xpointer_stuff" />

You can leave out either href (xi:include refers to the same file it is in then) or xpointer (xi:include then refers the complete file), but not both. href is expanded with wordexp internally, so you can do stuff like:

<xi:include href="$NAVIT_SHAREDIR/maps/*.xml" />

Some examples on the supported syntax:

<xi:include xpointer="xpointer(/config/navit/layout[@name='Car']/layer[@name='points'])" />

references to the XML-Tag "layer" with attribute "name" of value "points" within an XML-Tag "layout" with attribute "name" of value "Car" within an XML-Tag "navit" within an XML-Tag "config".

<config xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="$NAVIT_SHAREDIR/navit.xml" xpointer="xpointer(/config/*[name(.)!='navit'])"/>
<navit center="4808 N 1134 E" zoom="256" tracking="1" cursor="1" orientation="0">
<xi:include href="$NAVIT_SHAREDIR/navit.xml" xpointer="xpointer(/config/navit/*[name(.)!='vehicle'])"/>
</navit>
</config>

Use this as your $HOME/.navit/navit.xml and you will get everything under <config>..</config> except <navit>..</navit> (first xi:include), plus <navit> as specified plus everything from navit within config, except the vehicle definitions (second xi:include).


Full List of Options

This list of options was created based on the navit.dtd and the example navit.xml as of 14.08.08.

Tag Attribute Values Description
navit required The main container for all configurations. Must contain at least one mapset and layout; exactly one appearance of gui, graphics, tracking, route, navigation and speech; May contain an arbitrary number of vehicle
center required Coordinates The format is [D]DMM.SS[s][s] N/S [D][D]DMM.SS[s][s] E/W or [-][D]D.d[d]... [-][D][D]D.d[d]...
zoom required integer Initial zoom level (1 is the closest, no upper limit)
tracking required 1/0 Same as Display -> Lock on Road
cursor required 1/0 Show cursor for current position
orientation required 1/0 Same as Display -> Northing
gui required Contains settings for the user interface. Element is empty
type required name Selects the user interface: gtk / internal / cegui
menubar optional 1/0 Switches the menubar on/off
toolbar optional 1/0 Switches the toolbar on/off
statusbar optional 1/0 Switches the status bar on/off
skin optional name Selects the skin to use (default or Mineque)
fullscreen optional 1/0 Starts in fullscreen mode
graphics required Selects graphics
type required name Type of graphics to use: gtk_drawing_area / sdl / opengl
vehicle optional Vehicle definition. Element is empty
name required name Name of the vehicle
source required device path Source of gps data. e.g. file://dev/ttyS0 , gpsd://localhost, ...
gpsd_query required gpsd command Command to send to gpsd
color required #000000 Color of cursor
color2 optional Color of optional second cursor inside primary one
animate optional 1/0 Shows an animated cursor
enabled optional yes/no Show vehicle in gui menue
active optional 1/0 Select this vehicle by default
follow optional 1/0 Disables northing of map
refresh optional 1/0 Map follows the current vehicle position
tracking  ?
route required Describes properties of differnt route types. Contains an arbitrary number of speed elements
speed required Sets speed for a specific type of road
type required road type Selects type of road
speed required integer Sets speed for this type of road
navigation required Navigation related settings. Contains an arbitrary number of announce elements. Element is empty
announce required Settings for navigation announcements
type required list of types of roads
level0 optional integer distance for announcement
level1 optional integer distance for announcement
level2 optional integer distance for announcement
unit required unit measurement unit for above values


speech required Settings for speech outout
type required how to start speech output, i.e. "cmdline"
data required command for speech output, e.g. "spd-say -l de '%s'" or "flite -t '%s'"
mapset required Defines all maps. Must contain at least one map element.
enabled required yes/no Enable this set of maps
map required Defines a map
type required maptype type of map, e.g. binfile, garmin, mg
enabled required 1/0 Show map in menu
active required 1/0 Activate this map on startup
data required path Path to mapfile
debug required 1/0 Load in debug mode


To be continued.