donnees_meteo/docs/01 - Installation, configuration et tests/index.md

# Installation, configuration et tests

## Installation de l'environnement de base

Après avoir cloné le dépôt, on commence par préparer un environnement Python isolé pour ne pas polluer le système global et pouvoir supprimer facilement tout ce qui concerne ce projet.
L’idée est de regrouper au même endroit le moteur [`Python`](https://www.python.org/), les bibliothèques scientifiques et le client pour la base de données [`InfluxDB`](https://www.influxdata.com/), qui stocke nos séries temporelles.

```shell
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
python -c "import pandas, influxdb_client, sklearn; print('OK')"
```

- `python3 -m venv .venv` crée un environnement virtuel Python local dans le dossier `.venv`, ce qui permet d’isoler les paquets de ce projet du reste du système (voir par exemple la documentation sur les environnements virtuels [`venv`](https://docs.python.org/fr/3/library/venv.html)).
- `source .venv/bin/activate` active cet environnement dans le shell courant ; tant qu’il est actif, la commande `python` pointera vers l’interpréteur de `.venv` et non vers celui du système.
- `python -m pip install --upgrade pip` met à jour [`pip`](https://pip.pypa.io/), le gestionnaire de paquets de Python, afin d’éviter les bugs ou limitations des versions trop anciennes.
- `pip install -r requirements.txt` installe toutes les dépendances nécessaires au projet (notamment [`pandas`](https://pandas.pydata.org/), le client Python pour InfluxDB et [`scikit-learn`](https://scikit-learn.org/stable/) pour les modèles prédictifs) en suivant la liste déclarée dans `requirements.txt`.
- `python -c "import pandas, influxdb_client, sklearn; print('OK')"` vérifie que les principales bibliothèques s’importent correctement ; si la commande affiche `OK`, l’environnement de base est prêt à être utilisé.

## Configuration

```shell
cp .env.example .env
```

On copie le fichier de configuration d'exemple, puis on l'ouvre pour l'adapter à notre cas. Ce fichier `.env` sera lu automatiquement par les scripts via [`python-dotenv`](https://github.com/theskumar/python-dotenv) (voir `meteo/config.py`), ce qui évite d’exporter les variables à la main à chaque session.

- `INFLUXDB_URL` : URL de l'API du serveur InfluxDB 2.x (incluant généralement le port 8086), par exemple `http://localhost:8086` ou l’adresse de votre serveur ; c’est le point d’entrée HTTP/HTTPS vers votre base de données de séries temporelles (voir aussi l’introduction aux [bases de données de séries temporelles](https://fr.wikipedia.org/wiki/Base_de_donn%C3%A9es_de_s%C3%A9ries_temporelles)).
- `INFLUXDB_TOKEN` : jeton d'authentification généré dans l’interface d’[`InfluxDB 2.x`](https://docs.influxdata.com/influxdb/v2/), associé à un jeu de permissions (lecture/écriture) ; sans ce token, le client Python ne peut pas interroger le serveur.
- `INFLUXDB_ORG` : nom de l'organisation InfluxDB à laquelle le token est rattaché ; InfluxDB 2.x organise les ressources (utilisateurs, buckets, tokens) par organisation, il faut donc préciser celle que l’on souhaite utiliser.
- `INFLUXDB_BUCKET` : nom du bucket (espace logique de stockage avec sa politique de rétention) dans lequel les données sont enregistrées ; c’est ce bucket que les scripts interrogeront pour récupérer les mesures de la station.
- `STATION_LATITUDE` : latitude GPS de la station météo (en degrés décimaux), utilisée plus loin pour les calculs d’élévation solaire et pour enrichir les données avec des métadonnées astronomiques.
- `STATION_LONGITUDE` : longitude GPS de la station météo (en degrés décimaux), nécessaire pour les mêmes raisons que la latitude.
- `STATION_ELEVATION` : altitude de la station météo (en mètres au-dessus du niveau de la mer) ; cette information affine légèrement certains calculs physiques, mais reste optionnelle si l’altitude est mal connue.

## Tests de l'environnement de travail

Avant d’attaquer des analyses plus lourdes, on vérifie que la connexion au serveur InfluxDB fonctionne bien et que la configuration est cohérente.
Les scripts de test qui suivent n’écrivent rien dans la base : ils se contentent d’effectuer quelques requêtes simples pour valider l’accès.

```shell
python "docs/01 - Installation, configuration et tests/scripts/test_influx_connection.py"
```

```text
Configuration InfluxDB chargée :
  URL    : http://10.0.3.2:8086
  Org    : Dern
  Bucket : weather

→ Ping du serveur InfluxDB…
✔ Ping OK
→ Requête de test sur le bucket…
✔ Requête de test réussie : 18 table(s), 58 enregistrement(s) trouvés.
Exemple de point :
  time      : 2025-11-16 22:30:50.263360+00:00
  measurement : %
  field     : device_class_str
  value     : humidity
```

Si vous obtenez un résultat similaire (URL affichée, ping OK, requête de test qui retourne quelques enregistrements), c’est que le serveur InfluxDB est joignable, que le token est valide et que le bucket indiqué existe bien.

Ensuite, on peut demander à InfluxDB de nous détailler ce qu'il stocke :

```shell
python "docs/01 - Installation, configuration et tests/scripts/test_influx_schema.py"
```

```text
Bucket InfluxDB : weather

Measurements disponibles :
  - %
  - hPa
  - km/h
  - lx
  - mm/h
  - °
  - °C

Champs pour measurement « % » :
  - device_class_str (type: unknown)
  - friendly_name_str (type: unknown)
  - state_class_str (type: unknown)
  - value (type: unknown)

Champs pour measurement « hPa » :
  - device_class_str (type: unknown)
  - friendly_name_str (type: unknown)
  - state_class_str (type: unknown)
  - value (type: unknown)

Champs pour measurement « km/h » :
  - device_class_str (type: unknown)
  - friendly_name_str (type: unknown)
  - state_class_str (type: unknown)
  - value (type: unknown)

Champs pour measurement « lx » :
  - device_class_str (type: unknown)
  - friendly_name_str (type: unknown)
  - value (type: unknown)

Champs pour measurement « mm/h » :
  - device_class_str (type: unknown)
  - friendly_name_str (type: unknown)
  - state_class_str (type: unknown)
  - value (type: unknown)

Champs pour measurement « ° » :
  - friendly_name_str (type: unknown)
  - value (type: unknown)

Champs pour measurement « °C » :
  - device_class_str (type: unknown)
  - friendly_name_str (type: unknown)
  - state_class_str (type: unknown)
  - value (type: unknown)
```

Ce deuxième script interroge le schéma du bucket : il liste les _measurements_ (grandeurs physiques comme `%`, `°C`, `km/h`, etc.), ainsi que les champs associés à chacun.
Dans InfluxDB, un _measurement_ correspond en gros à un type de mesure (par exemple une unité), et les _fields_ contiennent les valeurs numériques que l’on exploitera plus tard ; les metadata (comme `entity_id`) sont stockées sous forme de _tags_ (voir la documentation sur le [modèle de données InfluxDB](https://docs.influxdata.com/influxdb/v2/reference/key-concepts/data-elements/)).

Mais pour obtenir les données dont on a besoin, il faut aussi connaitre les entités manipulées par Influx :

```shell
python "docs/01 - Installation, configuration et tests/scripts/test_influx_entities.py"
```

```text
Bucket InfluxDB : weather

Measurement « % »
  Tag keys :
    - _field
    - _measurement
    - _start
    - _stop
    - domain
    - entity_id
  entity_id possibles :
    - station_meteo_bresser_exterieur_humidite_relative

Measurement « hPa »
  Tag keys :
    - _field
    - _measurement
    - _start
    - _stop
    - domain
    - entity_id
  entity_id possibles :
    - station_meteo_bresser_exterieur_pression_atmospherique

Measurement « km/h »
  Tag keys :
    - _field
    - _measurement
    - _start
    - _stop
    - domain
    - entity_id
  entity_id possibles :
    - station_meteo_bresser_exterieur_vitesse_du_vent

Measurement « lx »
  Tag keys :
    - _field
    - _measurement
    - _start
    - _stop
    - domain
    - entity_id
  entity_id possibles :
    - station_meteo_bresser_exterieur_luminance

Measurement « mm/h »
  Tag keys :
    - _field
    - _measurement
    - _start
    - _stop
    - domain
    - entity_id
  entity_id possibles :
    - station_meteo_bresser_exterieur_precipitations

Measurement « ° »
  Tag keys :
    - _field
    - _measurement
    - _start
    - _stop
    - domain
    - entity_id
  entity_id possibles :
    - station_meteo_bresser_exterieur_direction_du_vent

Measurement « °C »
  Tag keys :
    - _field
    - _measurement
    - _start
    - _stop
    - domain
    - entity_id
  entity_id possibles :
    - station_meteo_bresser_exterieur_temperature
```

Ce dernier script fait le lien avec la source des données : il dresse la liste des clés de tags et des `entity_id` possibles pour chaque _measurement_.
Ces identifiants correspondent aux entités exposées par votre système domotique (par exemple [`Home Assistant`](https://www.home-assistant.io/)), et permettent de distinguer clairement l’humidité extérieure, la pression, la vitesse du vent, etc.

Ces informations combinées se retrouvent dans le fichier `meteo/station_config.py` et dans `meteo/variables.py` : c’est là que l’on fixe, une fois pour toutes, quelles entités InfluxDB seront considérées comme « température extérieure », « pluie », « vent », et sous quels noms elles seront manipulées dans la suite de l’étude.

On aurait pu se passer de ces scripts pour déterminer la structure des données stockées dans Influx, mais ils évitent de se reposer sur des intuitions : ici, on demande à Influx de nous donner les informations dont on va avoir besoin au lieu de les deviner.