Changeset 28 for trunk

Show
Ignore:
Timestamp:
05/02/08 12:28:32 (8 months ago)
Author:
relet.net
Message:

updated README file

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/README

    r1 r28  
    1 This is freimap release alpha-1. 
    2  
    3 Licence is GNU GPL. 
     1This is a freimap svn release. 
     2The Licence is GNU GPL. 
    43 
    54Copyleft by: 
    … …  
    76 * Robert Schuster <robertschuster@fsfe.org> 
    87 
    9 Freimap is a visualization environment for community mesh networks with 
    10 an OLSR infrastructure. Think "freifunk.net".  
     8Freimap is an Open Source visualization and analysis framework for (mostly) mesh networks, such as for example Freifunk.net. It can read many a different data source and display them as different layers. The network can be browsed and queried in real time, and a time bar allows to trace back to past events. Some statistics of the topology and network traffic may also be generated. 
    119 
    12 Documentation of the project is still expected to fall from the sky.  
    13 Until then, here's a small outlook of what you can get running and how. 
     10A thorough documentation of the project is still expected to fall from the sky. Until then, here's a small outlook of what you can get running and how. 
    1411 
    1512== Requirements == 
    1613 
    17 * Java 1.5.0 (Java2) or better (GCJ and GNU Classpath+Cacao works, but is slow and unstable) 
    18 * Either  
    19 ** olsr daemon running with the dot_draw plugin in the network 
    20 ** a database containing topology data, according to the provided SQL structure.  
    21 ** a server running the FreifunkMap software (http://www.layereight.de/software_freifunkmap.php) 
    22 * A few, rather common java libraries which are also provided in a separate convenience package 
    23 *# jFreeChart (1.0.4 checked) and jCommon (1.0.8 checked) from jfree.org 
    24 *# Mysql J/Connector if database access is used (version 5.0.5 checked) 
    25 *optional: an OpenStreetMap mapnik server providing tiles 
     14    * Java JDK 1.5.0 (Java2) or better. 
     15    * A few, rather common java libraries, which are provided in the svn version.  
     16 
     17To make good use of freimap, you would need some data sources. Some of these are 
     18 
     19    * Olsrd running with the dot_draw plugin, somewhere in the network. 
     20    * A latlon.js file, generated by the nameservice plugin. 
     21    * XML files containing node information, such as in certain freifunk maps. Some examples are provided in the data/ directory. 
     22    * A database containing node information, topology data, or flow data, according to the provided SQL structures.  
    2623 
    2724== Installation ==  
    2825 
    29 === from convenience JAR archive === 
     26Download the latest precompiled build: 
    3027 
    31 Assuming that you have the file freimap-all-*.jar in a convenient location. 
     28    * http://relet.net/trac/freimap/browser/freimap-latest.tbz?format=raw  
    3229 
    33  > unzip freimap-all-*.jar lib/* 
    34 :(will create a ./lib subfolder and extract libraries) 
     30or get the sources using 'svn': 
    3531 
    36 You're done.  
     32    * svn checkout http://relet.net/svn/freimap/trunk freimap  
    3733 
    38 === Compile from source jar archive ===  
     34=== Compiling (svn only) === 
    3935 
    40  > mkdir freimap 
    41 * Copy the jar file into this folder.  
    42  > jar xvf freimap-dev-*.jar  
    43 :(will create many a subfolder) 
    44  > ./compile  
    45 :(should compile the necessary files with a well-defined classpath, and create a jar file freimap.jar. If not, you'll have to adjust the file) 
     36    * ./compile (or "compile.bat")  
    4637 
    47 === Get the latest from SVN === 
     38or, if ant is available: 
    4839 
    49 * Follow the instructions at http://developer.berlios.de/svn/?group_id=8309 to obtain an up-to date source tree. 
    50  > ./compile 
    51 or, if you have ant installed: 
    52  > ant   
     40    * ant  
    5341 
    5442== Running freimap == 
    5543 
    56 By now, you should have the file freimap*.jar and a lib subfolder. 
     441. Configuration 
    5745 
    58 Copy config.yaml.example to config.yaml. Edit to taste. The configuration defaults to read a dot topology on localhost:2004.  
     46This is probably the trickiest part of the process. The configuration for freimap is stored in the configuration file "config.yaml" in the YAML markup language. An example file is provided as "config.yaml.example". Read the Configuration Manual in the freimap wiki for up-to-date details on the available options. 
    5947 
    60  > ./run  
    61 or  
    62  > java -Xmx500m -jar freimap-*.jar 
     48The example config file will create two layers: A list of nodes read from the provided xml file, and one displaying topology information from an olsrd dot_info plugin listening on localhost:2004. This is probably the most common and easiest to provide set of data sources. Another simple option would be to get a latlon.js file generated by the nameservice plugin of your olsr daemon. There's an example in the configuration manual, too.  
    6349 
    64 If you have got less than 500mb free memory, you may want to adjust the  
    65 -Xmx parameter. Freimap does not necessarily need that much unless you  
    66 evaluate many months of collected data using the MysqlDataSource.  
     502. Starting 
    6751 
     52    * ./run  
     53 
     54or 
     55 
     56    * java -Xmx500m -jar freimap.jar  
     57 
     58If you have got less than 500mb free memory, you may want to adjust the -Xmx parameter. Freimap does not necessarily need that much unless you evaluate many months of collected data.  
    6859 
    6960== Using freimap == 
    7061 
    71 You need geo-information for your network. Currently, this can be read  
    72 either from a Mysql Database, a nodes.dump file in the jar package or 
    73 from a FreifunkMap server. 
     62When freimap starts, the first thing it will do, is to parse the config file config.yaml. Beware, for since YAML is not very picky with its syntax, some typing errors in the structure may not be detected, and freimap will not necessarily complain if you made a mistake there. From the YAML data found in the config file, freimap will try to identify the Background and DataSource? layers to load, and initialize them with the given parameters. Layers will first be loaded, and initialized in a second run. Hence, cross-references should work from any layer to any other. 
    7463 
    75 The nodes.dump file however only provides data for nodes for a few 
    76 networks around Berlin and Leipzig currently. Importing from other 
    77 sources is on my to do list, suggestions are welcome.  
     64Freimap will output status information and error messages on the console while loading the layers and initializing data sources. For example 
    7865 
    79 In the main window, you will therefore see a number of white clouds at 
    80 first. They are the big node concentrations around Berlin and Leipzig. 
    81 Drag and zoom using your left and right mouse buttons to get closer to 
    82 the area where you expect to see your network. Press the play button at 
    83 the bottom of the screen to get live updates and display topology. (If you 
    84 don't see anything, try to zoom in near Berlin, Alexanderplatz where a big 
    85 green c-base logo is located. Any node which could not be located is currently 
    86 placed there - see [[Freimap/Troubleshooting]]) 
     66fetching node data from URL: file:latlon.js 
     67This may take a while ... finished. 
    8768 
    88 ======= 
     69would be the output of successfully loading node coordinates using a LatLonJsDataSource.  
    8970 
    90 In the main window, you will therefore see a number of white clouds at  
    91 first. They are the big node concentrations around Berlin and Leipzig.  
    92 Drag and zoom using your left and right mouse buttons to get closer to  
    93 the area where you expect to see your network. Press the play button at  
    94 the bottom of the screen to get live updates and display topology. (If you  
    95 don't see anything, try to zoom in near Berlin, Alexanderplatz where a big  
    96 green c-base logo is located. Any node which could not be located is currently  
    97 placed there - see [[Freimap/Troubleshooting]]) 
     71* The Graphical User Interface * 
    9872 
    99 === Configuration options === 
     73Once the freimap window appears, you should see a black-greenish screen, with some decorations and -if you have selected the OpenStreetMap? backdrop- a world map in the center. 
    10074 
    101 Obsolete. The new YAML syntax differs slightly but significantly. 
    102 I am keeping this here, as the options are basically the same. 
     75** Status Information ** 
    10376 
    104 ==== DataSource ==== 
    105 Set this to either net.relet.freimap.OLSRDDataSource, net.relet.freimap.MysqlDataSource 
    106 or net.relet.freimap.FreifunkMapDataSource. 
     77The second green bar on the top of the window displays your current location (longitude and latitude) and the map zoom factor. On the left side, where the URL of this site is displayed, at some point in the future, you might be able to see an actual place name. 
    10778 
    108 When using OLSRDataSource the dotdraw plugin of a running OLSR daemon is accessed to 
    109 retrieve live stats about the mesh-net. 
     79The bottom bar displays the currently selected time, and the memory usage of the software. When the 'resource usage' runs towards 100%, you may experience some OutOfMemoryErrors. This would usually happen when you work with larger quantities of data, which freimap currently seeks to keep in memory. 
    11080 
    111 When using  MysqlDataSource a MySQL database retrieves this information. 
     81** The Map / Navigation ** 
    11282 
    113 When using FreifunkMapDataSource the data is retrieved from a server running the  
    114 FreifunkMap scripts. 
     83The main portion of the screen is occupied by the map. At the beginning, you will find that it zoomed out to the maximum, so that you will have to zoom in to your preferred location first. If your data source has provided some node coordinates, you should be able to identify that location easily. 
    11584 
    116 ==== background ==== 
    117 Set this either to blank, images, openstreetmap in order to paint the application's 
    118 background with nothing, some images which are specified in the config file or 
    119 pre-rendered tiles of OpenStreetMap. 
     85Mouse control: 
    12086 
    121 ==== ffmds.url ==== 
    122 URL for a server running the FreifunkMap scripts or a local file which contains the 
    123 data the server would normally create. 
     87    * Left mouse button drag: Move the map 
     88    * Mouse wheel, or right button drag up/down: Zoom the map 
     89    * Double click: Print the current longitude/latitude to the console. 
     90    * Right click on a link or node: Begin fetching additional information (see section "Layers" below)  
    12491 
    125 The default configuration uses some sample data. 
     92Keyboard control - Currently supported: 
    12693 
    127 This is only needed if you use the FreifunkMapDataSource. 
     94    * '+' - Zoom in 
     95    * '-' - Zoom out  
    12896 
    129 ==== yaml.url ==== 
    130 No idea. 
     97** The Time Bar ** 
    13198 
    132 ==== olsrd.host, olsrd.port ==== 
    133 IP address and port of an OLSR daemon running the dotdraw plugin. 
     99The time bar at the bottom of the screen displays which data source has provided information for which time interval. A dark green bar represents the total interval where any data is available. Lighter green bars stacked on top represent the various data sources. You may directly click on the time bar to select a specific data set. 
    134100 
    135 This is only needed if you use the OLSRDDataSource. 
     101A red/green play button to the left of the bar allows you to replay the recorded data in order. Currently, the replay speed is a bit arbitrary. 
    136102 
    137 ==== olsrd.nodefile === 
    138 A file providing geographic information about OLSR nodes. The string 
    139 specifies a Java system resources. If unsure do not change the default. 
     103*Layers * 
    140104 
    141 This is only needed if you use the OLSRDDataSource. 
     105On the top left of the screen is a list of layers. Clicking on an item in this list will select it as the active layer, which reacts on your mouse actions. You may drag and drop layers to change the order of drawing. The eye icon to the left of the layer allows you to cycle between different display types of this layer - usually "on", "off" and "semi-transparent". More or less display types may be supported. 
    142106 
    143 ==== mysql.host, mysql.user, mysql.user, mysql.pass, mysql.db, mysql.tables.nodes, mysql.tables.links ==== 
    144 Credentials and table names for a MySQL database providing node data. 
     107Data Layers may react differently on your mouse actions. Their usage will be described in the following. 
     108** Node/Link Layers ** 
    145109 
    146 This is only needed if you use the MysqlDataSource. 
     110When moving over the displayed nodes and links, you will discover that the closest node or link to your mouse cursor will be highlighted. Additionally, an information pane is displayed on the top right of the screen. This information will display an identifier of the node or link, as well as more or less information provided by the data source. This list is usually followed by the words "+ right click for more +". 
    147111 
    148 ==== image.count ==== 
    149 The number of image entries in the config file. 
     112If you do right click, the data source will try to fetch further information concerning the given element. Depending on the element, this may include some statistics, generated over the available data, or add further elements to the information pane. This process may take some time. During this time, the information pane will display the message "retrieving information". When the process is finished, the additional information will be displayed automatically when hovering over the link. 
    150113 
    151 ==== image.X.gfx, image.X.lat, image.X.lon, image.X.scale ==== 
    152 An image entry where 'X' is a number. 'image.X.gfx' is a Java system resource string. 
    153 This means that your images must be available via the application's classpath. 
     114Another right click on the node or link may refresh the information, for example in the case of statistics and charts. 
    154115 
    155 === Interface === 
     116* The Menus * 
    156117 
    157 The main screen is a map where you can zoom and drag around. Status bars at the top and bottom will tell you about the currently displayed time and the geographical position equivalent to your mouse cursor.  
     118A menu bar is on top of the application. Currently, the only useful menu entries are the following. 
     119> View  
     120> Hide unlocated nodes  
    158121 
    159 * Left mouse button: Click and drag to move around the map 
    160 * Double click left on any place in the screen to center onto that place. 
    161 * Move your mouse over a node or a link to display basic information 
    162 * Right click onto a node or link to display advanced statistics. The displayed graphs require a certain minimum of time samples to be available, so that they may not work until after a certain while.  
    163 * Click and drag along the time line on the bottom of the screen to display information about another point in time. 
    164 * Click on the play/stop button to display a singe time or move forward within it.  
    165 * A drop down box at the top left of the screen allows you to center on a certain node. Since there are more than thousand registered nodes, it's not that useful currently.  
     122Stops/Starts interpolation and display of unlocated nodes. 
     123> Display Filter  
     124 
     125Selecting this menu will show a popup window which allows you to specify a display filter for nodes and links. To enable a filter, enter a string, select "enable display filter" and click on the "Apply" button. Now, only nodes containing (normal mode) or matching (regular expression mode) the specified string will be displayed.  
     126 
     127== Final Words == 
    166128 
    167129Enjoy!  
    168130Comments and bug reports are welcome. Either use the Bug reporting system  
    169 at http://freimap.berlios.de or contact me at the address above. 
     131at http://relet.net/trac/freimap or contact me at the address above. 
    170132