Skip to content

Latest commit

 

History

History
325 lines (227 loc) · 17.4 KB

installation-fr.adoc

File metadata and controls

325 lines (227 loc) · 17.4 KB
Raw

Installation

Sommaire

1. Introduction

L’application Occtax-mobile est une application Android et interagit avec un serveur GeoNature (2.4.0 minimum) et TaxHub (1.7.0 minimum).

Si vous souhaitez personnaliser l’application (nom, couleurs, icône), vous devez générer l’APK à partir des fichiers source comme détaillé dans la documentation de développement.

Sinon vous pouvez utiliser les APKs fournies dans les fichiers (assets) de chaque release (aux couleurs de certains parcs nationaux ou la version générique verte et rouge).

L’application Occtax-mobile embarque le module datasync qui gère notamment les données de GeoNature (observateurs, jeux de données, taxons, nomenclature, etc.) en faisant appel aux APIs de GeoNature. Toutes ces données sont stockées dans la base de données locale au format SQLite de l’application afin d’en disposer à tout moment et ainsi permettre un fonctionnement hors-ligne. Ce module permet aussi d’envoyer les données saisies sur le terminal mobile une fois que celui-ci dispose d’une connexion internet (wifi ou 4G). Ce module gère aussi la mise à jour automatique du fichier de configuration (à chaque démarrage de l’application), détecte et propose à l’utilisateur la mise à jour de l’application.

2. Pré-requis

  • Disposer de GeoNature et de TaxHub dans les versions compatibles avec la version d'Occtax-mobile que vous souhaitez installer.

  • Vos instances de GeoNature et TaxHub doivent être accessibles en HTTPS.

Architecture

2.1. Installation et configuration centralisées

Il est nécessaire de gérer les fichiers de configuration, l’installation et la mise à jour des applications au niveau du serveur GeoNature.

L’application Occtax-mobile se chargera alors de récupérer automatiquement sur le serveur GeoNature la dernière version du fichier de configuration des applications et détectera les éventuelles mises à jour disponibles pour l’application.

Pour cela, chargez l’APK de l’application Occtax-mobile ainsi que son fichier de configuration settings.json dans le dossier $HOME/geonature/backend/media/mobile/occtax du serveur GeoNature.

Dans les commandes ci-dessous, remplacez x.y.y par le numéro (tag) de la version (release) utilisée.

Sur votre serveur GeoNature, créez le sous-répertoire de l’application mobile Occtax-mobile.

cd ~/geonature/backend/media/mobile
mkdir occtax

​ Télécharger la version de Occtax-mobile souhaitée :

cd ../occtax
wget https://github.com/PnX-SI/gn_mobile_occtax/releases/download/x.y.z/occtax-y.y.z-generic-release.apk

Créer le fichier de settings settings.json en suivant la documentation en fonction de la configuration de votre serveur GeoNature.

Renseigner ensuite la table gn_commons.t_mobile_apps directement dans la base de données ou depuis le backoffice du module "Admin" de GeoNature.

Pour trouver la valeur à renseigner dans le champs version_code, celui-ci est mentionné dans les releases, ou reportez-vous au fichier suivant en sélectionnant le tag de version où la branche que vous utilisez :

Ou avec l’outil aapt (apt-get install aapt pour l’installer), exécutez la commande aapt dump badging applicationfile.apk | grep -Po "(?<=\sversion(Code|Name)'='')([0-9.]+)".

Exemple de contenu de la table gn_commons.t_mobile_apps :

1;"OCCTAX";"occtax/occtax-2.0.0-pne-debug.apk";"";"fr.geonature.occtax2";"2555"

Le résultat peut être testé en interrogeant directement la route <URL_GEONATURE>/api/gn_commons/t_mobile_apps qui est celle utilisée par l’application Occtax-mobile pour faire les mises à jour.

Installez ensuite l’application Occtax-mobile sur le terminal mobile.

Récupérer le fichier APK de la version souhaitée dans les fichiers de la release (assets)

Lancez l’application Occtax-mobile et déclarez l’URL de GeoNature et de TaxHub dans sa configuration (paramètres).

Le module de synchronisation se chargera de récupérer le fichier de configuration puis de lancer automatiquement une première synchronisation des données de GeoNature après authentification.

Si vous faites évoluer la configuration et/ou la version de l’application mobile sur le serveur GeoNature et dans la table gn_commons.t_mobile_apps, alors ils seront mis à jour sur le terminal mobile au prochain lancement de l’application Occtax-mobile.

3. Installation et configuration de l’application

Le fichier de configuration settings.json de l’application peut être directement copié dans le répertoire Android/data/fr.geonature.occtax2 sur le stockage interne du terminal mobile ou récupéré automatiquement lors de la première synchronisation avec le serveur GeoNature configuré (cf. Installation et configuration centralisées).

Dans tous les cas, l’installation et la configuration centralisée devront être mis en place pour que la synchronisation des données fonctionne. Le fichier de configuration sur le serveur écrasera celui sur le terminal à chaque lancement de l’application Occtax-mobile.

Le paramètre page_size permet de paginer les appels aux routes renvoyant de nombreux résultats et ainsi les récupérer par lots.

Exemples des routes paginées :

  • <URL_TAXHUB>/api/taxref/allnamebylist/100?limit=100&offset=200 (pour renvoyer les noms des 100 taxons à partir du 200ième résultat des taxons de la liste 100)

  • <URL_GEONATURE>/api/synthese/color_taxon?code_area_type=M10&limit=10&offset=20 (pour renvoyer 10 résultats à partir du vingtième résultat des couleurs des taxons pour les zonages de type Mailles de 10km)

Le comportement de la synchronisation consiste à appeler au maximum n fois la route paginée tant que celle-ci retourne un tableau de valeurs non vides et que ce tableau a la même taille que page_size.

Les conditions d’arrêt de l’interrogation de ces routes sont :

  • Tableau de valeurs vide

  • Taille du tableau de valeurs < page_size

  • Erreur 404

Le paramètre code_area_type correspond au type de zonage de votre référentiel géographique de GeoNature (champs type_code de la table ref_geo.bib_areas_types) utilisé pour les unités géographiques. Voir PnX-SI/gn_mobile_core#15.

Le paramètre gn_application_id permet de renseigner l' id_application de GeoNature dans la table utilisateurs.t_applications pour l’authentification des utilisateurs et leurs droits.

Le paramètre observers_list_id permet de renseigner l' id_liste des observateurs d’Occtax dans la table utilisateurs.t_listes.

Le paramètre taxa_list_id permet de renseigner l' id_liste des taxons saisissables dans Occtax dans la table taxonomie.bib_listes.

Le paramètre area_observation_duration est lié aux couleurs des taxons dans chaque unités géographiques en fonction de la date de dernière observation du taxon dans l’unité géographique.

Il correspond à la durée en jours définie dans la vue gn_synthese.v_color_taxon_area permettant d’ajuster à quelle fréquence un taxon change de couleur selon sa date de dernière observation dans l’unité géographique (plus d’un mois, plus d’un an, plus de 5 ans, etc.).

Voir PnX-SI/GeoNature#617 et #50 pour plus de détails.

Pour la configuration de la partie cartographique (attribut map du fichier settings.json), se référer au README du module Maps.

Cette partie permet de définir l’affichage des outils cartographiques, le centrage l’étendue et les niveaux de zoom, mais aussi les fonds et couches cartographiques de l’application.

Le module Maps s’appuie sur la bibliothèque osmdroid et gère notamment les sources locales (https://github.com/osmdroid/osmdroid/wiki/Offline-Map-Tiles) pouvant être généré via les outils QGIS (Traitements > générer des tuiles XYZ), MOBAC ou Maperitive.

Charger un fond de carte (MBTiles, les autres formats doivent aussi fonctionner) sur le terminal mobile et renseigner son chemin dans le paramètre base_path.

La page Paramètres de l’application Occtax-mobile indique les chemins absolus de la carte interne et éventuellement de la carte SD externe.

Il n’est cependant pas obligatoire de préciser le chemin pour résoudre le chargement des fonds de carte. L’application va privilégier la carte SD externe (si présente) et à défaut la mémoire interne. Le paramètre base_path peut prendre un chemin absolu (pour une résolution rapide), un chemin relatif (selon le point de montage, par exemple Android/data) ou être omis. Dans ce dernier cas, la résolution sera plus lente car elle impliquera un scan complet des stockages du terminal mobile.

ℹ️

Sur Android 11 et supérieur, l’application Occtax-mobile nécessitera d’avoir les permissions pour gérer l’espace de stockage, ceci afin de pouvoir déterminer automatiquement l’emplacement des fonds de carte sur le terminal (cf. PnX-SI/gn_mobile_maps#7).

manage external storage
Figure 1. Demande d’accès à tous les fichiers

Il est possible de charger différents fonds cartographiques (Scan et Ortho par exemple) mais aussi d’afficher des couches vectorielles.

On peut ajouter autant de couches vectorielles et pour chacune on peut appliquer des styles différents. Vous pouvez vous référer au README du module Maps pour le paramétrage.

Il est possible d’utiliser et d’afficher une couche vectorielle de polygones d’unités géographiques (mailles, habitats, zonages etc.). Cela permet d’afficher une couleur différente aux taxons de la liste selon la date de dernière observation dans l’unité où le relevé a été localisé (via synchronisation des données de la synthèse de GeoNature). Il est également possible de filtrer la liste des taxons selon ce critère.

Pour cela, il est nécessaire de charger une couche vectorielle de polygones des unités géographiques en respectant quelques règles.

La couche d’unités géographiques doit être issue des entités qui peuplent la table ref_geo.l_areas.

Le code du type de zonage utilisé doit être renseigné dans le paramètre code_area_type du fichier settings.json de gn_mobile_core. Ce même code doit aussi être renseigné dans le paramètre occtaxmobile_area_type de la table gn_commons.t_parameters de la base de données de GeoNature.

Par défaut, si aucune couche vectorielle n’est configurée, l’application va simplement charger la base des taxons sans les informations additionnelles venant des unités géographiques.

Il est important que l’ID de chaque zone corresponde à ce que remonte GeoNature pour faire la correspondance.

L’attribut area_id des données de la route /geonature/api/synthese/color_taxon correspond à l’identifiant présent dans la couche vectorielle.

⚠️
 Pour que les couleurs de taxons soient synchronisées sur l’ensemble des unités géographiques choisies, il est nécessaire d’adapter la pagination et le nombre de résultats renvoyés par les routes en tenant compte du nombre d’entités présentes dans la vue gn_synthese.v_color_taxon_area. Pour ce faire, modifiez le fichier settings.json de l’application de l’application Occtax-mobile directement coté GeoNature. L’application se chargera de le mettre à jour localement lors de son prochain redémarrage.

Les couches vectorielles peuvent être au format json, geojson ou wkt:

WKT:

  • Fichier texte au format CSV où chaque ligne comporte la description d’une géométrie au format WKT

  • La géométrie doit être encodée dans le SCR WGS84:EPSG4326

  • Le type de géométrie doit être POLYGON (et non MULTIPOLYGON)

  • L’extension du fichier doit être .wkt et le fichier ne doit pas contenir d’en-tête

  • Chaque ligne doit commencer par un identifiant puis, la géométrie ce qui donne ceci :

    <id>,<geometry>; …​

    Par exemple :

    110,POINT (-1.5487664937973022 47.21628889447996)
108,POINT (-1.5407788753509521 47.241763083159455)

  • dans le fichier au format WKT (chaîne de caractères), la géométrie ne doit pas être en guillemets (quotes). Exemple :

    660993,POLYGON (((6.73181863107186 45.7539143085928,6.74466771917198 45.7534881584565,6.74405801858532 45.7444934010459,6.73121101630907 45.7449194816323,6.73181863107186 45.7539143085928)))

json, geojson

  • Fichier texte au format JSON contenant un objet de type FeatureCollection ou un tableau d’objets de type Feature

  • La géométrie doit être encodée dans le SCR WGS84:EPSG4326

  • Chaque objet de type Feature doit comporter un identifiant (attribut id), en tant qu’attribut de cet objet ou en tant que propriété de cet objet. Par exemple :

    {
  "id": 1234, (1)
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      -1.5545135,
      47.2256258
    ]
  },
  "properties": {
    "name": "Ile de Versailles"
  }
}

    1. identifiant de la géométrie

      {
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      -1.5545135,
      47.2256258
    ]
  },
  "properties": {
    "id": 1234, (1)
    "name": "Ile de Versailles"
  }
}

    2. identifiant de la géométrie

4. Serveur de démonstration

Il est possible de tester l’application mobile en la connectant sur le serveur de démonstration.

Pour cela, télécharger l’application Occtax-mobile et installez-la sur un terminal mobile. Lancez l’application et renseignez dans ses paramètres l’URL du serveur de démo de GeoNature (https://demo.geonature.fr/geonature).

Authentifiez-vous avec l’utilisateur de démo (admin / admin). L’application se chargera de télécharger le fichier de configuration puis lancera automatiquement une première synchronisation des données.

Vous pouvez aussi utiliser les fichiers d’exemple de fond de carte et d’unités géographiques (mailles 10x10km), disponibles dans le dossier https://geonature.fr/data/maps/ et en les copiant dans le dossier que vous souhaitez sur le stockage interne ou la carte SD du terminal.

5. Logs

Pour obtenir des logs de l’application mobile, on peut :

  • les récupérer directement sur l’appareil mobile, dans le répertoire des logs de l’application (Android/data/fr.geonature.occtax2/logs)

  • utiliser l’utilitaire adb (Android Debug Bridge est intégré au kit de développement d’Android Studio mais peut aussi être installé à part).

5.1. adb

Sous Linux :

sudo apt-get install android-tools-adb

Sous Windows, vous pouvez installer le petit logiciel Minimal ADB and Fastboot (https://forum.xda-developers.com/showthread.php?t=2317790).

Activer le Débogage USB dans les options développeur de votre terminal mobile et connectez-le en USB à votre PC.

Sous Linux, dans le terminal ou sous Windows dans le terminal de Minimal ADB, lancer la commande permettant les appareils mobiles connectés :

adb devices

Cette commande doit lister votre appareil mobile si celui-ci est bien détecté. Il peut être nécessaire d’autoriser la connexion sur l’appareil mobile.

Pour obtenir les logs liés à l’application Occtax-mobile, exécutez la commande :

Sous Linux :

adb logcat | grep fr.geonature

Sous Windows :

adb logcat | findstr fr.geonature