*******************************
*  M y B l i t z o r t u n g  *
*******************************                               ####
                                                              ####
                                                              #### 
                                                             ####
                                                             ####
                                                            ###
                                                           ###      #####
                                                           ###    ### ###
                                                          ###   ###  ###
MyBlitzortung (MyBo) is a tool for participants          ### ###    ###
of the lightning detection network blitzortung.org,      ## ##     ##  
to display lightning data on their web sites             ####     ##
Look at                                                          ##
                                                                ##
    http://www.myblitzortung.de                                 #
                                                                # 
for further information and demonstrations.                   #####
                                                               ###
                                                                #

YOU HAVE TO BE A MEMBER OF BLITZORTUNG.ORG TO INSTALL THIS APPLICATION!



Chapters
--------

  1. Licence
  2. Requirements
  3. Support
  4. Helping
  5. Installation and Update
  6. Configuration
  7. Website Integration
  8. Description of special features
     a) Archive maps
     b) Strike densities
     c) Alerts
     d) Antenna calibration
  9. FAQ
 10. Miscanellous
 11. Thanks

        
**************
* 1. LICENSE *
**************

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.


Additional licensing hints
--------------------------
    
Some maps and images are included in this package. All maps are free, but have different licenses! 

== Maps created with map tool on blitzortung.org (Data from ETOPO Ice Surface) ==

- Europe (normal and mini)
- Germany (only mini)
- Switzerland


== Wikipedia / Wikimedia Commons ==

- Germany ("Landkreise" / counties)
  Created by user TUBS 
  see http://de.wikipedia.org/w/index.php?title=Datei:Landkreise,_Kreise_und_kreisfreie_St%C3%A4dte_in_Deutschland.svg
  Be careful: This map has no real mercator projection, strike positions are not exact!
  Feel free to create a better map from free sources!
  
- Germany (Bavaria/NRW) 
  Wikimedia Commons, Licence GNU-Documentation or CC-BY-SA 
  see http://commons.wikimedia.org/wiki/File:Bavaria_relief_location_map.jpg)
  
  

*******************
* 2. REQUIREMENTS *
*******************

- Apache web server (other web servers untested)
- MySQL 5 (Version 4 untested)
- PHP 5 (it won't work with PHP4!)
- about 100 MB of free memory for database and cache files (and much more if you want to archive all data)




**************
* 3. SUPPORT *
**************

- See FAQ in this document

- See this thread: http://www.wetter-board.de/index.php?page=Thread&threadID=47554
  Of course, you can ask questions there in english. It would also be great to hear of successful installations.

- Official Blitzortung FAQ Site: http://www.wetter-ybbs.at/blitzortung-faq/




**************
* 4. HELPING *
**************

EVERYBODY CAN HELP BY SUPPORTING OTHER USERS AND BY DEVELOPING THIS PROGRAM!

- Adding new translations
- Improve and add features
- Adding maps of other countries
- Find AND report bugs
- Support other users




*******************
* 5. INSTALLATION *
*******************

1. Get the files
----------------

Download the archive from:
--> https://github.com/tobiasv/MyBlitzortung

Be careful: You should download a tagged version, otherwise you will get the developer code, which may not work properly!


2. Copy the files
-----------------

Copy the files from the archive to your webserver (usually with FTP).
For example, we use the directory "mybo" here, or in the browser "http://yourdomain.tld/mybo".


3. Call the installation script
-------------------------------

Call "http://yourdomain.tld/mybo/install". The installer will guide you through the installation process. 
The hardest thing is to create your own "config.php". The database will be installed automatically. See chapter 6. for additional config.php options and a configuration example.


4. Change permission of the cache directories
---------------------------------------------

Change permissions of the directories, so that the web server can write in it. Usually the permissions are set to "777".
- cache
- cache/tiles
- cache/maps
- cache/icons


5. Setup data import
--------------------

Now you have to set up the automatic data import. The link for that is displayed in the last step of the installation process. You can create an own cron entry, or an entry in the windows tasks. The easiest way is to use an external provider like http://cronjob.de

Update frequency: You can call the URL every minute. There is an internal timer, that prevents accessing the files on the blitzortung server to much. Default settings for this timer for strike updates is 5 Minutes, for stations 15 and for signals 60. You can change these values in config.php.


6. Configuration
----------------

The essential configuration was already done in config.php. But there are a lot of other settings, that you can change or add individually in this file. See next chapter for more details.


7. Install JpGraph
------------------

JpGraph is used for creating the graphs. You can get it at http://jpgraph.net/download/ . Copy the files from the JpGraph "src" direcory to includes/jpgraph. You can omit the directories src/barcode, src/Examples, src/themes and all files beginnig width <em>flag</em>. No further installation is needed!


8. Check if everything works
----------------------------

Call http://yourdomain.tld/mybo and you should see the map. You can now login with your blitzortung username and password.

Please see next chapter for configuration options!


UPDATING
========

To update MyBlitzortung you have to download the new archive, extract it and copy the new files over the old files. Your own files (config.php, individual maps) shouldn't be overwritten. Immediately after that, you should enter the user area, to automatically update the database.

Downgrading might not work this way! 

Note: Before the update, you should always create a backup of your database!



********************
* 6. CONFIGURATION *
********************

All configuration options can be set in your own config.php. There are a lot of more configuration options, than described here. For more info see includes/default_settings.inc.php , but do NOT edit this file (otherwise, your settings will be overwritten the next update).


a) CONSTANTS
============

A note on defining constants in PHP. Example:

    -----------------------------------------------------------
    define(BO_CONSTANT, "Test value"); // string
    define(BO_CONSTANT, 12345);        // number
    define(BO_CONSTANT, "12345");      // number as string
    define(BO_CONSTANT, null);         // null = nothing
    -----------------------------------------------------------

Sets BO_CONSTANT to the string "Test value". Sometimes you need to enter false or true. Don't use quotes with them!!! 

    ------------------------------------------------
    define(BO_CONSTANT, "true");  //NOT CORRECT
    define(BO_CONSTANT, "false"); //NOT CORRECT
    define(BO_CONSTANT, true);    //Good!
    define(BO_CONSTANT, false);   //Good!
    ------------------------------------------------


b) INDIVIDUAL CONFIGURATION
===========================

1. Set up data purging
----------------------

The size of the database may grow VERY fast. For that, an automatic data purging is integrated. 

- BO_PURGE_ENABLE: Enables/Disables data purging completly (it is not advised to set it to "false").
- BO_PURGE_MAIN_INTVL: The main interval (in hours) for data purging.

With the other constants BO_PURGE... you can individually set up purging by specifying a minimum before old data will be deleted. See includes/default_settings.inc.php for all available constants. The following two settings should be enabled:

- BO_PURGE_STRSTA_ALL: Deletes the assignments for strikes to every stations (your station is saved elsewhere). This data grows VERY fast! You can set it to 24 hours or less.
- BO_PURGE_SIG_NS: Your signal (raw) data. Can also get very big, especially if your station sends much signals per hour.



2. Radius and zoom levels
-------------------------

- BO_RADIUS: The maximum radius around your station, where guests can see all strikes on every zoom level. You should leave it at 50 kilometers.
- BO_DEFAULT_ZOOM: Default zoom level on first visit
- BO_MAX_ZOOM_LIMIT: When the zoom is greater than value, only strikes in defined distance to your station are displayed (for guests)
- BO_MAX_ZOOM_IN: Overall maximum zoom
- BO_MIN_ZOOM_OUT: Overall minimum zoom



3. Maps, strike densities, overlays, regions
--------------------------------------------

You can add more maps, overlays for the dynamic map, regions and density calculations. The configuration of these objects is done by variables. Here is an example:


   The main map (Google map) is configured with by the array $_BO['mapcfg']. 
   Every time range has its own array. These are the default settings:
    - $_BO['mapcfg'][0] ... for the first (0-15min)
    - $_BO['mapcfg'][1] ... for the second (15-120min)
    - $_BO['mapcfg'][2] ... for the third (2-24h)
    - ...


You will find more information about that on this webpage:
--> http://www.myblitzortung.de/myblitzortung_config_maps?lang=en

You can also have a look at the files /includes/default_settings.inc.php and /includes/templates.php . But do not edit them! All your individual configuration has to be done in config.php!

For developing own images, you should set BO_CACHE_DISABLE to true. This disables the internal file cache and reloading an image in the browser (i.e. with F5 key) will display the new image. You can also clear the cache whenever you did changes to that files.





c) EXAMPLE config.php
=====================

    ------------------------------------------------------------------------------------------------------------------------------
    <?php

    /**
      * Main Config file for MyBlitzortung
     *
     * The following 10 constants have to be defined!
     */

    /
    //Database
    define("BO_DB_USER", "mybouser");
    define("BO_DB_PASS", "password");
    define("BO_DB_NAME", "myblitzortung");
    define("BO_DB_HOST", "localhost");
    define("BO_DB_PREF", "bo_");

    //Station Settings
    define("BO_LAT", 49.39);
    define("BO_LON", 10.88);
    define("BO_STATION_NAME", "MyCity");

    //blitzortung.org Login
    define("BO_USER", "MaxMuster");
    define("BO_PASS", "bla");

    
    /**
      *  The whole rest from here is not necessary  !
      */
    
    
    //if your mysql server has another port set it here:
    define("BO_DB_PORT", 3306);
    
    //Secret for update
    define('BO_UPDATE_SECRET', 'abcdefg123');
    
    //Path and file settings
    define("BO_FILE", '/mypath/blitzortung.php');
    define("BO_LOGIN_URL", 'intern');
    define("BO_ARCHIVE_URL", 'archiv?');

    //Language
    define("BO_LOCALE", 'de');
    define("BO_UTF8", true);

    //global purge settings
    define("BO_PURGE_ENABLE", false);   //disable purging ==> build your archive !

    //archive and densities
    define("BO_ENABLE_ARCHIVE_MAPS", true); //Enables archive (maps by date and animations) for guests
    define("BO_ENABLE_DENSITIES", true); //Enables densities for guests (set the also next option to true)
    define("BO_CALC_DENSITIES", true); //Calculate densities
    define("BO_CALC_DENSITIES_CURRENT", true); //Calculates Densities for current year/month
    define("BO_DENSITY_STATIONS", '1,2,3'); //Additional station ids

    //Alerts: E-Mail headers
    define('BO_EMAIL_HEADERS', "From: Blitzalarm <kontakt@weather-somewhere.com>\r\nX-Mailer: PHP/".phpversion());
    
    //SMS gateway
    define("BO_SMS_GATEWAY_URL", 'http://gateway.sms77.de/?u=user&p=password&to={tel}&text={text}&type=quality&from=MyBO');


    /*** Add your own map ***/
    //MyCity (example)
    $_BO['mapimg'][3]['name'] = 'MyCity';
    $_BO['mapimg'][3]['footer'] = '&copy; OpenStreetMap und Mitwirkende, <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>';
    $_BO['mapimg'][3]['menu'] = true;
    $_BO['mapimg'][3]['archive'] = true;
    $_BO['mapimg'][3]['file'] = 'map_mycity.png';
    $_BO['mapimg'][3]['coord'] = array(49.606, 11.25, 49.163, 10.544); //North, East, South, West (Degrees)
    $_BO['mapimg'][3]['trange'] = 2; //hours!
    $_BO['mapimg'][3]['upd_intv'] = 5; //minutes
    $_BO['mapimg'][3]['textcolor'] = array(0,0,60);
    $_BO['mapimg'][3]['textsize'] = 5;
    $_BO['mapimg'][3]['point_type'] = 1;
    $_BO['mapimg'][3]['point_size'] = 7;
    $_BO['mapimg'][3]['legend'] = array(5, 100, 80, 4, 4, 1);
    $_BO['mapimg'][3]['col'][] = array(255, 255, 0);
    $_BO['mapimg'][3]['col'][] = array(255, 200, 0);
    $_BO['mapimg'][3]['col'][] = array(255, 150, 0);
    $_BO['mapimg'][3]['col'][] = array(255, 100, 0);
    $_BO['mapimg'][3]['col'][] = array(255,   0, 0);
    $_BO['mapimg'][3]['col'][] = array(225,   0, 0);
    $_BO['mapimg'][3]['show_station'] = array(5, 155,80,155,false);
    $_BO['mapimg'][3]['density'] = true;
    $_BO['mapimg'][3]['density_blocksize'] = 40;
    $_BO['mapimg'][3]['density_darken'] = 70;
    $_BO['mapimg'][3]['density_colors'][] = array(150, 150, 250, 95);
    $_BO['mapimg'][3]['density_colors'][] = array(50, 150, 155, 90);
    $_BO['mapimg'][3]['density_colors'][] = array(205, 205, 50, 85);
    $_BO['mapimg'][3]['density_colors'][] = array(230, 0, 0, 80);
    $_BO['mapimg'][3]['density_colors'][] = array(255, 0, 255, 75);
    $_BO['mapimg'][3]['density_colors'][] = array(255, 190, 255, 70);

    
    //use the a better germany map (from templates)
    $_BO['mapimg'][2] = $_BO['tpl_imgmap']['germany_lkr_gdz'];
    
    //unset the europe map
    $_BO['mapimg'][0] = array();

    //enable 1 to 10day strike view for logged in users (from template)
    $_BO['mapcfg'][3] = $_BO['tpl_gmap']['1-10d'];

    ?>
    -----------------------------------------------------------------------------------------------------------------------------

    
    

**************************
* 7. WEBSITE INTEGRATION *
**************************

MyBlitzortung was designed to be included seamlessly in your own homepage. No Javascript in the body or somewhere else is needed, only two or more lines with PHP code. Of course, you need some basic PHP experience for that. For a first example you should look in the file index.php in the MyBlitzortung root directory.

Here's an example of integrating the main map into a web page:

    --- yourphpfile.php ----------------------------------
    <html>

    <head>
        
        ...
        
        <link rel="stylesheet" href="path/to/myblitzortung/style.css" type="text/css"> 
        <link rel="stylesheet" href="own_style.css" type="text/css"> 
        
        ...
        
    </head>
    
    <body>
    
    ....
    Your HTML or PHP code
    ....

    <div id="myblitzortung">
    <?php
    include "path/to/myblitzortung/blitzortung.php";
    bo_show_map();
    ?>
    </div>

    ...
    
    </body>
    </html>
    ----------------------------------------------------

Important things:

1. MyBo needs know, where the "blitzortung.php" resides. Set the constant BO_FILE to the URL to this file or create your own php file which simply includes the "blitzortung.php" an set BO_FILE the url of that file.
2. Same thing with the other sites. As you can integrate them in a site of your own, MyBo needs to know the URL to those sites. So you should also set BO_ARCHIVE_URL and BO_LOGIN_URL to the correct url (the other constants are not used by MyBo).
3. In the example above, there's also the default MyBo style included. It only applies to the div-container with id "myblitzortung". You do not need this, but it should be easier this way to change the style in your own css file.


PHP Functions that can be integrated in an existing site
========================================================

- bo_show_map()
  Shows the main map.

- bo_show_archive()
  The Archive.

- bo_show_statistics()
  Statistics and graphs.

- bo_show_info()
  General and additional information.

- bo_show_login()
  Login screen and user area.

  
The following function includes all functions above.

- bo_show_all()
  Shows one of the five areas from above, according to the GET-Variable "bo_page". 
  The bo_page can be one of the following values: map, archive, statistics, info, login

- bo_show_menu()
  Shows the main menu. For usage with bo_show_all().




*************************************
* 8. DESCIPTION OF SPECIAL FEATURES *
*************************************

a) ARCHIVE MAPS
===============

To enable the archive maps and animations, set BO_ENABLE_ARCHIVE_MAPS to true. The daily strike maps and animations will be available to guests.


b) STRIKE DENSITIES
===================

Currently very experimental! Enable with BO_ENABLE_DENSITIES and BO_CALC_DENSITIES. When enabled, the densities are calculated automatically on month change. You can enable BO_CALC_DENSITIES_CURRENT to calculate the data every day for current month year (NOT ADVISED!).

You can calculate densities and strike ratios for other station with 

   define("BO_DENSITY_STATIONS", "1,2,3"); //comma separated list of station numbers.

You can change density settings with $_BO['density']. For displaying densities on maps see $_BO['mapimg'][x]['density'] an so on. Look in default_settings.inc.php and templates.inc.php for more details!



c) STRIKE ALERTS
================

You can define strike alerts. MyBlitzortung will automatically send an E-Mail or SMS when strikes in an individually specified area occur.

Hints
-----

Strike counts are always checked after data import. Too much alerts can cause high load. If you let the marker position exactly on your station, this checking will be faster. Raising the max. distance or the time interval too much will also cause high load. Don't go higher than 15 minutes and 50 kilometers.

Please note that the distance calculation for the alerts is currently not very exact. It's currently not a circle, but more a square in which new strikes are searched. 

About sending alerts
--------------------

After an alert was send, this alert will be "disarmed" and the next check for this specific alert will occur after BO_ALERT_CHECK_INTERVAL minutes. If strike count is still high enough, it will stay "disarmed" again for BO_ALERT_CHECK_INTERVAL and so on. If strike count is lower than selectet count, the next timer is BO_ALERT_SEND_INTERVAL. No alert will be send for given minutes and no strike-checking will be made. After this time, a new alert would be sent if enough strikes occur in the selected area.

SMS configuration
-----------------

First you need to register at an SMS-gateway. Some examples:

- smstrade.de
- sms77.de
- innosend.de

I prefer smstrade.de but the others should also work. You will get a username/password and perhaps an individual key for usage with their API. You have to set the constant BO_SMS_GATEWAY_URL correctly. {text} and {tel} are placeholders for text an the phone number. Example:

  http://gateway.smstrade.de/?key=1234567891234566&to={tel}&message={text}&from=MyBO&route=gold 


  
d) ANTENNA CALIBRATION
======================

This works only with magnetic antennas, but it works very well if enough strikes and signals where recorded.  Finding the electrical directions ist VERY experimental! For further informations please ask on wetter-board.de (see link in Chapter "Support"). 

If you set up the electrical bearings of your antennas, then the polarity will be displayed on the main strike map. Set BO_EXPERIMENTAL_POLARITY_CHECK to false to disable the polarity calculation. With BO_EXPERIMENTAL_POLARITY_ZOOM you can set the zoom level, on which polarity is displayed.



e) LINKING WITH OTHER MYBLITZORTUNG STATIONS
============================================

You can automatically link with other MyBlitzortung station. The other stations will then be displayed on the dynamic strike map.

Simply click the link in the admin user area. Your coordinates (BO_LAT/BO_LON), maximum distance (BO_RADIUS) and the url of your website will be transfered to www.myblitzortung.de. You will get back the information of the other stations. Please read the hints about privacy! 





***********
* 9. FAQ  *
***********

1. Nothing works
================

Set BO_DEBUG in the config.php file to true an look for error messages. Double check you installation and try to reinstall MyBo.
A common failure: Wrong text mode. Use the correct text mode of your PHP installation, in 99.9% this is linux text mode. You can convert it with free editors like Notepad++. Or use WinSCP to access your web server per FTP. Don't access your FTP with Internet Explorer!

If you get a Error 500 message (blank page) you should enable reporting in your webserver. To do that, create a file named ".htaccess" (without quotes!) an fill it with this single line:

  php_value display_errors 1

Now you should see the php error messages. If not, you can also search for an error_log file on your webspace. This file is provided by your hoster and can reside in different folders.


2. Update shows "NO UPDATE!"
============================

This is ok! It is the integrated timer. Use the force option to force updating new data (the link when logged in as admin does the same).


3. Antialiasing Graphs
======================

JpGraphs default setting use antialiasing images. This looks nice, but takes much more CPU usage and thick lines are not available. Some PHP installations don't have the required builtin GD-lib. It is disabled by default (BO_GRAPH_ANTIALIAS set to false).


4. My CPU load gets very high
=============================

One reason could be the calculating of statistics of other stations during import. You can disable this by setting BO_STATION_STAT_DISABLE to true.

The creation and downloading of the map tiles can cause VERY high CPU load. If you have a temporarily high visitor count on your website, you could disable the Google map, by setting BO_MAP_DISABLE to true.


5. Cronjob doesn't work
=======================

Do NOT use blitzortung.php as a command like "/path/to/blitzortung.php?update" as the whole cron job command line. Nothing will be updated! You have to get the url with http! You can do this with "wget". Example:

  wget -O - 'http://www.xxx.net/mybo/blitzortung.php?update&secret=...' &> /dev/null

Wget will retrieve the data.


I is also possible to run the update from command line with PHP. For example

  > php /filesystem/path/to/blitzortung.php update
Or
  > php /filesystem/path/to/blitzortung.php update force

On most systems this should work too.


6. No Graphs
============

Perhaps you didn't copy all JpGraph files. Call a graph image directly, for example with this url: blitzortung.php?graph_statistics=strikes

a) You don't see errors, but no image is displayed: Enable error reporting as described in FAQ 1. above. If you then see errors, that's good! In most cases they tell you what to do. After that, disable error reporting again.

b) If you see error messages, you can try to disable them (see FAQ 1 above). 




********************
* 10. MISCANELLOUS *
********************

1. Changing one or more texts or messages
=========================================

Create file "locales/own.php" and enter your own messages. See "own_example.php" for more details.
DON'T edit the other locales like en.php , because they will be overwritten on each update!


2. See strike details
=====================

When logged in, right click on a strike on the main map to open a new window with further information. Works only on higher zoom levels.


3. Do not display exact coordinates of my station
=================================================

You don't have to set the constants BO_LAT and BO_LON to your exact station coordinates. They may be some 100 Meters away from your real coordinates. You can also set BO_SHOW_GPS_INFO (no output at "other statistics) to false, so nobody can see your real station coordinates.


4. Changing styles
==================

This only applies if you are using MyBo as standalone program: Create a file own.css in the MyBo folder and enter your individual styles. Some examples:


a) Hide title "MyBlitzortung"

    --- own.css ----------------------------
    
    #mybo_head h1 {
        display: none;
    }
    
    ----------------------------------------

    
b) Change size of the main map

    --- own.css ----------------------------
    
    #myblitzortung #bo_gmap { 
        width: 123px !important; 
        height: 234px !important; 
    } 
    
    ----------------------------------------

	
	
****************
* 10. CREDITS  *
****************

Special thanks go to Egon and his Team for this great project! 

Big thanks to all other Blitzortung.org members that helped creating this cool app.


Localisations
=============
- de: tobi
- en: tobi
- fr: flc85