Merge pull request #20 from PnEcrins/develop

Merge suite à la modification de la doc

README.rst

@@ -23,7 +23,30 @@ Technologies
 Présentation
 ------------
 
-Principe général : ...
+**Principe général** : 
+
+L'application permet de suivre la position et le délacement de plusieurs objets équipés d'un GPS. 
+
+Les objets ont chacun un identifiant. Ils transmettent tous leur position GPS à un satellite à intervalles réguliers. 
+
+Il faut ensuite récupérer ces positions GPS des objets pour les intégrer dans la base de données MySQL. Pour cela un fichier TXT par position et par objet est envoyé à une boite email.
+
+Une tâche (``import_imap_csv`` dans le fichier ``/classes/controler/controler.class.php``) permet de : 
+
+- Se connecter à cette boite email et d'en extraire les fichiers TXT en pièce-jointe des emails
+- Copier ces fichiers TXT dans le répertoire ``tmp/csv``
+- Supprimer les emails une fois les fichiers TXT copiés sur le serveur
+- Importer les nouvelles positions des différents objets (si ceux-ci existent dans la BDD avec un identifiant commun) dans un fichier CSV (``/csv/tracked_objects.csv``)
+- Supprimer les fichiers TXT temporaires une fois qu'ils ont été traités
+- Importer les nouvelles positions dans la BDD MySQL depuis le fichier ``/csv/tracked_objects.csv``
+- Vider le fichier ``/csv/tracked_objects.csv``
+
+Cette tache peut être lancée manuellement ou par un CRON lancé autmatiquement à intervalle régulier.
+
+D'autres manières de remplir ce CSV pourraient être envisagées : 
+
+- Remplir directement le fichier CSV automatiquement ou à la main
+- Importer les fichiers TXT dans le répertoire ``tmp/csv`` sans passer par une connection à une boite email.
 
 Installation
 ------------

docs/configuration.rst

@@ -5,68 +5,101 @@ CONFIGURATION
 Principe de l'application
 =========================
 
-L'application utilise des données transmises par des objets équipés d'un GPS.
+**Principe général** : 
 
-Le traitement de ces données s'effectue en plusieurs étapes.
+L'application permet de suivre la position et le délacement de plusieurs objets équipés d'un GPS. 
 
-Tout d'abord, les GPS envoient leurs positions aux satellites.
+Les objets ont chacun un identifiant. Ils transmettent tous leur position GPS à un satellite à intervalles réguliers. 
 
-Ensuite, les satellites envoient les données en pièce jointe sur une boîte mail, ces fichiers sont des fichiers txt.
+Il faut ensuite récupérer ces positions GPS des objets pour les intégrer dans la base de données MySQL. Pour cela un fichier TXT par position et par objet est envoyé à une boite email. 
 
-L'application a la possibilité de traiter les données de deux manières :
+Le fichier TXT (nommé ``T5HS-4183_2014-07-31_185705.txt`` où ``4183`` est l'identifiant de l'objet et les chiffres suivants sont la date et l'heure) est construit de la sorte :
 
-- On peut renseigner les données dans le fichier ``tracked_objects.csv`` en respectant la forme ci-dessous.
-- On peut récupérer les fichiers txt dans les pièces jointes des emails sur la boîte spécifique. Par la suite, ils sont traités selon la correspondance définie dans le fichier ``config.php`` puis transformés en CSV standard de l'application.
-
-Le fichier csv est constitué de plusieurs colonnes
-
-* Id de l'objet.
+::
 
-* Nom de l'objet.
+    2014-07-31	20:57:05+0	44.989867	6.022400	(-)0
+    
+    Date	Time	TTF	Lat	Long	SAT´s	2D/3D	Alt	H-DOP	Temp	X	Y	
+    2014-07-31	18:57:00	100	44.9901367	 6.0225950	6	3D	  2547	3.5	 14	 46	 29
 
-* Date de l'envoi des données au satellite.
+Dans cet exemple, le fichier contient :
 
-* Heure de l'envoi des données au satellite.
+- la date et l'heure du relevé GPS
+- le TTF (Time To First Fix, temps mis pour obtenir la position GPS de l'objet)
+- la latitude et longitude en WGS84
+- le nombre de satellites qui ont permis de définir la position
+- si la position a été fournie en 2D ou en 3D
+- l'altitude de la position
+- le H-DOP (Dilution Of Precision, coefficient de précision de la position)
+- la température (fournie par le GPS)
+- X et Y (non utilisées)
 
-* TTF (pas utilisé)
+Une tâche (``import_imap_csv`` dans le fichier ``/classes/controler/controler.class.php``) permet de : 
 
-* Latitude.
+- Se connecter à cette boite email et d'en extraire les fichiers TXT en pièce-jointe des emails
+- Copier ces fichiers TXT dans le répertoire ``tmp/csv``
+- Supprimer les emails une fois les fichiers TXT copiés sur le serveur
+- Importer les nouvelles positions des différents objets (si ceux-ci existent dans la BDD avec un identifiant commun) dans un fichier CSV (``/csv/tracked_objects.csv``)
+- Supprimer les fichiers TXT temporaires une fois qu'ils ont été traités
+- Importer les nouvelles positions dans la BDD MySQL depuis le fichier ``/csv/tracked_objects.csv``
+- Vider le fichier ``/csv/tracked_objects.csv``
 
-* Longitude.
+Cette tache peut être lancée manuellement (``url/controler/import_imap_csv``) ou par un CRON lancé autmatiquement à intervalle régulier.
 
-* Nombre de satellites.
+Pour mettre en place le CRON qui va lancer cette tache toutes les heures, éditez la liste des CRON du serveur : 
+::
+	crontab -e
 
-* 3D ou 2D. (si c'est on 3D on a l'altitude)
+Ajouter cette ligne dans le fichier (en remplacant ``URL_FollowDem`` par l'URL de votre application) : 
+::
+	#BOUQUETINS Import des donnees toutes les heures
+	0 */1 * * * wget http://URL_FollowDem/controler/import_imap_csv -O - >> /var/www/followdem/logs/imports.log
 
-* Altitude de l'objet.
+Les résultats de la tache lancée automatiquement toutes les heures seront écrits dans le fichier de log ``/logs/imports.log``.
 
-* H-DOP. (permet de connaître la fiabilité de la position)
+D'autres manières de remplir ce CSV pourraient être envisagées : 
 
-* Température.
+- Remplir directement le fichier CSV automatiquement ou à la main
+- Importer les fichiers TXT dans le répertoire ``tmp/csv`` sans passer par une connection à une boite email.
 
-* X (pas utilisé)
+Le fichier CSV est constitué de plusieurs colonnes :
 
-* Y (pas utilisé)
+- Id de l'objet.
+- Nom de l'objet.
+- Date de l'envoi des données au satellite.
+- Heure de l'envoi des données au satellite.
+- TTF (pas utilisé)
+- Latitude.
+- Longitude.
+- Nombre de satellites.
+- 3D ou 2D. (si c'est on 3D on a l'altitude)
+- Altitude de l'objet.
+- H-DOP. (permet de connaître la fiabilité de la position)
+- Température.
+- X (pas utilisé)
+- Y (pas utilisé)
 
-L'import des données se fait avec une tâche CRON, mais on peut lancer un script qui s'occupe d'importer les données directement.
+Les colonnes et leur ordre dans le CSV sont configurables dans le paramètre ``$config['csv_colonne']`` du fichier ``/config/config.php``
+Il est possible de définir des seuils de valeur pour lesquelles on ne souhaite pas intégrer les positions dans la BDD (Nombre de satellites trop faible, H-DOP trop élevé, latitude, longitude ou altitude incohérentes,...) avec le paramètre ``$config['csv_condition']`` dans le fichier ``/config/config.php``.
 
 Configurer l'application
 ========================
 
-Rendez vous dans le fichier ``config.php``, c'est ce fichier qui est la base de la configuration de l'application.
+Rendez vous dans le fichier ``/config/config.php``, c'est ce fichier qui est la base de la configuration de l'application.
+
 Modifier nom de domaine de l'application
 ::
 	$config['url'] = 'http://mon-domaine.com';
 	
-Changer le titre de l'entête sur l'application
+Changer le titre de l'application
 ::
 	$config['titre_application'] = 'FollowDem';
 
-Modifier l'url vers un formulaire de contact
+Modifier l'URL vers un formulaire de contact
 ::
 	$config['emailContact'] = 'http://mon-domaine.com/nous-contacter';
 	
-Proposer plusieurs langues disponible (complétez le array en suivant la logique ci-dessous)
+Définir les langues disponibles (complétez le array en suivant la logique ci-dessous)
 ::
 	$config['langue_dispo'] = array('fr_FR'=>'fr','us_US'=>'us');
 
@@ -78,27 +111,27 @@ Choisir un fuseau horaire
 ::
 	$config['fuseau'] = 'Europe/Paris';
 
-Modifier l'encodage par défaut
+Modifier l'encodage de l'application par défaut
 ::
 	$config['encodage'] = 'UTF-8';
 
 Changer l'encodage de la date de sortie
 ::
 	$config['datesortie'] = '%a %e %b %Y - %H:%M';
 
-Définir la date minimale de non mise-à-jour des données (les données sont valides si elles ne sont pas plus anciennes que la valeur donnée)
+Définir la durée en jours minimale de non mise-à-jour des données (un objet est désactivé si il n'a pas reçu de données pendant cette durée)
 ::
 	$config['date_data_valide'] = 150;
 
-Changer la période minimale de suivi d'un objet
+Changer la période minimale de suivi d'un objet (en jours)
 ::
 	$config['periode_min'] = 15; 
 
 Changer la période maximale de suivi d'un objet
 ::
 	$config['periode_max'] = 360;
 	
-Modifier les périodes possibles pour le suivi d'un objet
+Modifier les périodes possibles pour le suivi d'un objet (affiché sous forme de liste déroulante)
 ::
 	$config['periode_valeurs'] = array(3,15,30,60,90,120,150,180,210,240,270,300,330,360);
 
@@ -110,56 +143,56 @@ Modifier le répertoire de l'application
 ::
 	$config['rep_appli'] = '/var/www/followdem';
 	
-Définir le séparateur dans les fichiers csv
+Définir le séparateur dans les fichiers CSV
 ::
 	$config['csv_separateur'] = ',';
 
 Définir le paramètre d'exclusion de caractères spéciaux
 ::
 	$config['csv_enclosure'] = '"';
 
-Modifier le nom du fichier csv de l'application
+Modifier le nom du fichier CSV contenant les données à importer dans la BDD
 ::
 	$config['csv_name'] = 'tracked_objects.csv';
 
-Modifier le répertoire qui contient le fichier csv
+Modifier le répertoire qui contient ce fichier CSV
 ::
 	$config['csv_repertoire'] = 'csv';
 
-Définir les colonnes du fichier csv que vous voulez utiliser
+Définir les colonnes du fichier CSV que vous voulez utiliser
 ::
 	$config['csv_colonne'] = array('id'=>0,'nom'=>1,'date'=>2,'heure'=>3,'latitude'=>5,'longitude'=>6,'temperature'=>11,'nb_satellites'=>7,'altitude'=>9);
 
 Affecter l'Id d'un objet à un nom d'objet
 ::
 	$config['csv_nom_tracked_objects'] = array();
 
-Changer l'email de réception des erreurs de traitement des fichiers csv
+Changer l'email de réception des erreurs de traitement des fichiers CSV
 ::
 	$config['csv_email_error_nom'] = array('monPrenom'=>'exemple@domaine.com');
 
 Choisir si la transmission d'email d'erreur lors de l'import est autorisée
 ::
 	$config['csv_email_error'] = false;
 
-Récupérer des propriétés supplémentaires dans le csv
+Récupérer des propriétés supplémentaires dans le CSV
 ::
 	$config['csv_colonne_objects_features'] = array();
 
-Modifier le format de date du fichier csv
+Modifier le format de date du fichier CSV
 ::
 	$config['csv_date_format'] = 'Y-m-d';
 	
-Modifier le format de l'heure du fichier csv
+Modifier le format de l'heure du fichier CSV
 ::
 	$config['csv_heure_format'] = 'H:i:s';	
 	
-Changer la restriction d'import de certaines données dans le fichier csv
+Changer les restrictions d'import de certaines données dans le fichier CSV
 ::
 	$config['csv_condition'] = array(array(5,'>0'),array(6,'>0'),array(9,'>1000'),array(9,'<4102'));
 	$config['csv_condition_type'] = array(5=>'numeric',6=>'numeric',9=>'numeric');
 
-Modifier les paramètres de la base de données
+Modifier les paramètres de connexion à la base de données
 ::
 	$config['db_host'] 		= 	'localhost';
 	$config['db_name'] 		= 	'dbname';
@@ -193,7 +226,7 @@ Définir la durée de vie du cache serveur Smarty
 ::
 	$config['smarty_cache_lifetime'] = 120;
 
-Paramétrer les fonds de cartes utilisés par l'application, si vous utilisez les fonds de cartes IGN, pensez à remplacer la valeur de maCleIgn dans 'url'
+Paramétrer les fonds de carte utilisés par l'application. Si vous utilisez les fonds de cartes IGN, pensez à remplacer la valeur de ``maCleIgn`` dans ``url``
 ::
 	$config['leaflet_fonds_carte'] = array(
 			"IGNCARTE"=>array(
@@ -246,19 +279,19 @@ Changer les pictogrammes utilisés par Leaflet
 		)
 	);
 	
-Choisir la position de centrale initial sur la carte
+Choisir la position de centrage initial sur la carte
 ::
 	$config['leaflet_centrage_initiale'] = array('44.845159','6.310043');
 	
-Modifier le zoom initial sur la carte
+Définir le zoom initial sur la carte
 ::
 	$config['leaflet_zoom_initial'] = 11;
 
-Modifier le zoom maximal sur la carte
+Définir le zoom maximal sur la carte
 ::
 	$config['leaflet_zoom_max'] = 17;
 
-Changer la position des icônes de zoom sur la carte
+Définir la position des icônes de zoom sur la carte
 ::
 	$config['leaflet_position_zoom'] = 'topright';
 
@@ -286,13 +319,13 @@ Modifier le style des derniers points en fonction des paramètres contenus dans
 ::
 	$config['lefleat_style_point_surcharge'] = array('color'=>"couleurD","fillColor"=>"couleurG","Opacity"=>1,"fillOpacity"=>0.9,"weight"=>5);
 
-Paramétrer le suivi statistique de l'application	
+Paramétrer le suivi statistique de l'application (Google Analytics dans cet exemple avec ID à remplacer par le votre)	
 ::
 	$config['active_tracking_stats'] = 'true';
 	$config['tracking_stats'] = "
 	<script type='text/javascript'>
 		var _gaq = _gaq || [];
-		_gaq.push(['_setAccount', 'UA-7988554-6']);
+		_gaq.push(['_setAccount', 'ID_GOOGLE_ANALYTICS_A_MODIFIER']);
 		_gaq.push(['_trackPageview']);
 		(function() {
 			var ga = document.createElement('script');

docs/index.rst

@@ -1,12 +1,16 @@
 Bienvenue dans la doc de FollowDem
 ==================================
 
+FollowDem est une application web cartographique permettant de suivre le déplacement d'objets équipés d'un GPS.
+Utilisée pour le suivi GPS des bouquetins du Parc national des Ecrins : <http://bouquetins.ecrins-parcnatonal.fr>`_
+
 Contenu:
 
 .. toctree::
    :maxdepth: 2
 
    server
    installation
+   configuration
    auteurs
-   changelog
+   changelog