Skip to content

Commit 12f8d80

Browse files
authored
docs: amélioration du README et suggestion d'affichage sous forme de badge (#40)
* docs: amélioration et correction du README (orthographe, clarté, exemples, badges Mushroom) * review
1 parent b4bff4f commit 12f8d80

2 files changed

Lines changed: 147 additions & 49 deletions

File tree

README.md

Lines changed: 147 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,47 @@
11
# Atmo France pour Home Assistant
2-
![downloads](https://img.shields.io/badge/dynamic/json?color=41BDF5&logo=home-assistant&label=integration%20usage&suffix=%20installs&cacheSeconds=15600&url=https://analytics.home-assistant.io/custom_integrations.json&query=$.atmofrance.total)
32

3+
![downloads](https://img.shields.io/badge/dynamic/json?color=41BDF5&logo=home-assistant&label=integration%20usage&suffix=%20installs&cacheSeconds=15600&url=https://analytics.home-assistant.io/custom_integrations.json&query=$.atmofrance.total)
44

55
Composant pour exposer les niveaux de pollution atmosphérique et alerte pollen prévus pour le jour même et le lendemain.
66

77
Données fournies par Atmo France et les agences régionales.
88
Voir https://www.atmo-france.org/ pour l'accès web.
99

1010
L'intégration expose les données d'Atmo France pour une commune donnée.
11+
1112
Les données exposées pour la pollution de l'air sont :
13+
1214
- Niveau de pollution Dioxyde d'Azote (NO<sub>2</sub>)
1315
- Niveau de pollution Ozone (O<sub>3</sub>)
1416
- Niveau de pollution Dioxyde de Soufre (SO<sub>2</sub>)
1517
- Niveau de pollution Particules fines <2.5 µm (Pm25)
1618
- Niveau de pollution Particules fines <10 µm (Pm10)
1719
- Niveau global de qualité de l'air
1820

19-
Les données exposées pour les pollens sont :
21+
Les données exposées pour les pollens sont :
22+
2023
- Concentration en Ambroisie (µg/m<sup>3</sup>)
2124
- Concentration en Armoise (µg/m<sup>3</sup>)
2225
- Concentration en Aulne (µg/m<sup>3</sup>)
2326
- Concentration en Bouleau (µg/m<sup>3</sup>)
24-
- Concentration en Graminé (µg/m<sup>3</sup>)
27+
- Concentration en Graminées (µg/m<sup>3</sup>)
2528
- Concentration en Olivier (µg/m<sup>3</sup>)
2629
- Niveau Ambroisie
2730
- Niveau Armoise
2831
- Niveau Aulne
2932
- Niveau Bouleau
30-
- Niveau Graminé
33+
- Niveau Graminées
3134
- Niveau Olivier
3235
- Qualité globale Pollen
3336

34-
Sont disponibles , les données pour le jour courant (J) ainsi que les prévisions pour le jour suivant (J+1).
37+
Sont disponibles les données pour le jour courant (J) ainsi que les prévisions pour le jour suivant (J+1).
3538

3639
> [!IMPORTANT]
37-
> Prévisions disponible à J+1. Sous réserves de présence effective des données.
40+
> Prévisions disponibles à J+1, sous réserve de la présence effective des données.
3841
>
39-
> Les données étant rafraichies à 12h00, entre 00h00 et 12H00 du jour J, les données à J+2 ne sont pas disponibles.
42+
> Les données étant rafraîchies à 12h00, entre 00h00 et 12h00 du jour J, les données à J+2 ne sont pas disponibles.
4043
>
41-
> C'est pour cette raison que les prévisions à J+2 ne sont pas implémentés.
42-
44+
> C'est pour cette raison que les prévisions à J+2 ne sont pas implémentées.
4345
4446
## Installation
4547

@@ -56,7 +58,7 @@ Utilisez [HACS](https://hacs.xyz/).
5658

5759
### Configuration dans Home Assistant
5860

59-
La méthode de configuration consiste à utiliser l'interface utilisateur.
61+
La configuration s'effectue via l'interface utilisateur.
6062

6163
Il faut tout d'abord saisir ses [identifiants d'accès](#obtenir-un-accès-pour-les-api-atmo-france) à l'API.
6264

@@ -65,93 +67,103 @@ Il faut tout d'abord saisir ses [identifiants d'accès](#obtenir-un-accès-pour-
6567
Puis sélectionner le code postal de la commune dont on souhaite obtenir les données.
6668

6769
![image info](/img/location.png)
68-
>**Note :**
69-
>L'API se base sur le code INSEE. La récupération du code INSEE se fait via l'intégration, mais il peut y avoir plusieurs communes (donc plusieurs codes INSEE) pour un même code postal. Dans ce cas, une étape supplémentaire demande de préciser la commune (sélectionnable dans une liste) pour ne récupérer qu'un code INSEE.
70+
71+
> **Note :**
72+
> L'API se base sur le code INSEE. La récupération du code INSEE se fait via l'intégration, mais il peut y avoir plusieurs communes (donc plusieurs codes INSEE) pour un même code postal. Dans ce cas, une étape supplémentaire demande de préciser la commune (sélectionnable dans une liste) pour ne récupérer qu'un code INSEE.
7073
7174
![image info](/img/multiloc.png)
7275

73-
>**Note:**
74-
> Pour certaines région (Occitanie, Bretagne), les données sont disponibles au niveau de l'[EPCI](https://www.insee.fr/fr/metadonnees/definition/c1160#:~:text=Les%20%C3%A9tablissements%20publics%20de%20coop%C3%A9ration,%C3%A0%20celles%20de%20collectivit%C3%A9s%20locales) et non de la commune.
75-
> L'intégration le detecte automatiquement et affiche les donnée de l'EPCI à laquelle la commune appartient.
76+
> **Note :**
77+
> Pour certaines régions (Occitanie, Bretagne), les données sont disponibles au niveau de l'[EPCI](https://www.insee.fr/fr/metadonnees/definition/c1160#:~:text=Les%20%C3%A9tablissements%20publics%20de%20coop%C3%A9ration,%C3%A0%20celles%20de%20collectivit%C3%A9s%20locales) et non de la commune.
78+
> L'intégration le détecte automatiquement et affiche les données de l'EPCI à laquelle la commune appartient.
7679
>
7780
> La configuration se fait toujours par le code postal de la commune, mais l'extraction des données au niveau EPCI.
7881
79-
Ensuite, il faut sélectionner le type d'informations souhaité les indicateurs de pollution et/ou les données concernant les pollens.
82+
Ensuite, il faut sélectionner le type d'informations souhaité : les indicateurs de pollution et/ou les données concernant les pollens.
8083

8184
![image info](/img/typeindicateur.png)
8285

83-
8486
Enfin, il faut choisir d'ajouter ou non des prévisions pour les polluants et/ou les données pollens.
8587

8688
![image info](/img/forecast_initial.png)
8789

88-
>**Note :**
89-
>Lors de la mise à jour du composant depuis une version précédente:
90-
> - les donnes pollens ne sont pas actuves. Pour rajouter les données pollen, passer par le menu *Configuer* de l'entité et activer les indicateurs pollens.
91-
> - les données prévisions ne sont pas actives. Pour rajouter les prévisions, passer par le menu *Configuer* de l'entité et activer les indicateurs de prévision.
90+
> **Note :**
91+
> Lors de la mise à jour du composant depuis une version précédente :
92+
>
93+
> - les données pollens ne sont pas actives. Pour rajouter les données pollens, passer par le menu _Configurer_ de l'entité et activer les indicateurs pollens.
94+
> - les données prévisions ne sont pas actives. Pour rajouter les prévisions, passer par le menu _Configurer_ de l'entité et activer les indicateurs de prévision.
9295
9396
![image info](/img/configuration.png)
9497

9598
### Données
9699

97100
#### Pollution
98-
Les informations présentées sont les niveaux de pollution sur une échelle de 1 (Bon) à 6 (Extrêmement Mauvais), avec 0 (Indisponible) et 7 (événement).
99101

100-
Les attributs suivants sont disponible:
101-
- La date et heure (UTC) de la mise à jour des données par AtmoFrance. **Les données sont mises à jour une fois par jour par Atmo France.**
102+
Les informations présentées sont les niveaux de pollution sur une échelle de 1 (Bon) à 6 (Extrêmement Mauvais), avec 0 (Indisponible) et 7 (Événement).
103+
104+
Les attributs suivants sont disponibles :
105+
106+
- La date et heure (UTC) de la mise à jour des données par Atmo France. **Les données sont mises à jour une fois par jour par Atmo France.**
102107
- Le libellé du niveau
103-
- La couleur associée au niveau de pollution (couleurs 'officielles' d'atmo france, au format hexadécimal)
108+
- La couleur associée au niveau de pollution (couleurs 'officielles' d'Atmo France, au format hexadécimal)
104109
- Le type de zone (commune ou EPCI)
105110
- Le nom de la zone
106111

107112
![image info](/img/attributs.png)
108113

109114
#### Pollens
110-
Les informations présentées sont les niveaux d'alerte pollen sur une échelle de 1 (Trés Faible) à 6 (Extrêmement Elevé), avec 0 (Indisponible) et la concentration des pollens en µg/m<sup>3</sup>.
111115

112-
Les attributs suivants sont disponible:
113-
- La date et heure (UTC) de la mise à jour des données par AtmoFrance. **Les données sont mises à jour une fois par jour par Atmo France vers 13h00**
116+
Les informations présentées sont les niveaux d'alerte pollen sur une échelle de 1 (Très Faible) à 6 (Extrêmement Élevé), avec 0 (Indisponible) et la concentration des pollens en µg/m<sup>3</sup>.
117+
118+
Les attributs suivants sont disponibles :
119+
120+
- La date et heure (UTC) de la mise à jour des données par Atmo France. **Les données sont mises à jour une fois par jour par Atmo France vers 13h00**
114121
- Le libellé du niveau (**uniquement pour le niveau**)
115-
- La couleur associée au niveau de pollution (couleurs 'officielles' d'atmo france, au format hexadécimal) (**uniquement pour le niveau**)
122+
- La couleur associée au niveau de pollution (couleurs 'officielles' d'Atmo France, au format hexadécimal) (**uniquement pour le niveau**)
116123
- Le type de zone (commune ou EPCI)
117124
- Le nom de la zone
118125

119-
120126
![image info](/img/attributsPollens.png)
121-
### Suggestion d'affichage
127+
128+
## Suggestion d'affichage
129+
130+
### Decluttering Card
122131

123132
#### Pollution
124133

125134
![Dashboard](img/dashboard.png)
126-
### Pollen
135+
136+
#### Pollen
127137

128138
![alt text](img/dashboard2.png)
129139

130-
:warning: **Prérequis** Cet affichage se base sur les composants:
131-
- [custom-button-card](https://github.com/custom-cards)
132-
- [decluttering-card](https://github.com/custom-cards/decluttering-card)
140+
:warning: **Prérequis** Cet affichage se base sur les composants :
141+
142+
- [custom-button-card](https://github.com/custom-cards)
143+
- [decluttering-card](https://github.com/custom-cards/decluttering-card)
133144

134145
Se référer à la doc de chacun des composants pour les détails.
135146

147+
Configuration _modèle decluttering_
136148

137-
Configuration *modèle decluttering*
138-
``` yaml
149+
```yaml
139150
decluttering_templates:
140-
atmofrance:
141-
card:
142-
type: custom:button-card
143-
entity: '[[sensor]]'
144-
name: |
145-
[[[
146-
return entity.attributes.friendly_name +' : ' + entity.attributes.Libellé
147-
]]]
148-
styles:
149-
icon:
150-
- color: '[[[return entity.attributes.Couleur]]]'
151+
atmofrance:
152+
card:
153+
type: custom:button-card
154+
entity: "[[sensor]]"
155+
name: |
156+
[[[
157+
return entity.attributes.friendly_name +' : ' + entity.attributes.Libellé
158+
]]]
159+
styles:
160+
icon:
161+
- color: "[[[return entity.attributes.Couleur]]]"
151162
```
152163
153164
Configuration du dashboard principal :
154-
``` yaml
165+
166+
```yaml
155167
type: vertical-stack
156168
cards:
157169
- type: custom:decluttering-card
@@ -181,3 +193,89 @@ cards:
181193
variables:
182194
- sensor: sensor.dioxyde_de_soufre_paris
183195
```
196+
197+
### Mushroom badge
198+
199+
Une autre façon d'afficher les données sous forme de badge.
200+
201+
![Badge](img/badge.png)
202+
203+
:warning: **Prérequis** Cet affichage se base sur le composant :
204+
205+
- [Mushroom](https://github.com/piitaya/lovelace-mushroom)
206+
207+
Configuration du badge :
208+
209+
Cet exemple peut servir de point de départ : vous pouvez personnaliser l'affichage du titre et du contenu selon vos préférences. Dans cet exemple, le titre affiche les principaux polluants et le contenu indique l'indice de qualité de l'air. N'oubliez pas d'adapter les entités à votre configuration.
210+
211+
<details>
212+
<summary>Afficher le code YAML</summary>
213+
214+
```yaml
215+
type: custom:mushroom-template-badge
216+
entity: sensor.qualite_globale_decines_charpieu
217+
color: "{{state_attr('sensor.qualite_globale_decines_charpieu','Couleur')}}"
218+
tap_action:
219+
action: more-info
220+
icon: mdi:molecule
221+
content: "{{state_attr('sensor.qualite_globale_decines_charpieu','Libellé')}}"
222+
label: >-
223+
{% set ozone = states('sensor.ozone_decines_charpieu') | float(0) %} {% set
224+
pm10 = states('sensor.pm10_decines_charpieu') | float(0) %} {% set so2 =
225+
states('sensor.dioxyde_de_soufre_decines_charpieu') | float(0) %} {% set pm25
226+
= states('sensor.pm25_decines_charpieu') | float(0) %} {% set no2 =
227+
states('sensor.dioxyde_d_azote_decines_charpieu') | float(0) %}
228+
229+
{% set max_value = [ozone, pm10, so2, pm25, no2] | max %}
230+
231+
{% set max_labels = [] %}
232+
233+
{% if ozone == max_value %}{% set max_labels = max_labels + ['O3'] %}{% endif
234+
%} {% if pm10 == max_value %}{% set max_labels = max_labels + ['PM10'] %}{%
235+
endif %} {% if so2 == max_value %}{% set max_labels = max_labels + ['SO₂']
236+
%}{% endif %} {% if pm25 == max_value %}{% set max_labels = max_labels +
237+
['PM2.5'] %}{% endif %} {% if no2 == max_value %}{% set max_labels =
238+
max_labels + ['NO₂'] %}{% endif %}
239+
240+
{{ max_labels | join(', ') }}
241+
```
242+
243+
</details>
244+
245+
Le même principe s'applique pour les pollens : le titre affiche la liste des principaux pollens et le contenu indique le niveau de risque pollinique. Modifiez le code YAML en fonction de vos besoins.
246+
247+
<details>
248+
<summary>Afficher le code YAML</summary>
249+
250+
```yaml
251+
type: custom:mushroom-template-badge
252+
entity: sensor.qualite_globale_pollen_decines_charpieu
253+
color: "{{state_attr('sensor.qualite_globale_pollen_decines_charpieu','Couleur')}}"
254+
tap_action:
255+
action: more-info
256+
icon: mdi:flower-pollen-outline
257+
content: "{{state_attr('sensor.qualite_globale_pollen_decines_charpieu','Libellé')}}"
258+
label: >-
259+
{% set ambroisie = states('sensor.niveau_ambroisie_decines_charpieu') |
260+
float(0) %} {% set armoise = states('sensor.niveau_armoise_decines_charpieu')
261+
| float(0) %} {% set aulne = states('sensor.niveau_aulne_decines_charpieu') |
262+
float(0) %} {% set bouleau = states('sensor.niveau_bouleau_decines_charpieu')
263+
| float(0) %} {% set gramine =
264+
states('sensor.niveau_gramine_decines_charpieu') | float(0) %} {% set olivier
265+
= states('sensor.niveau_olivier_decines_charpieu') | float(0) %}
266+
267+
{% set max_value = [ambroisie, armoise, aulne, bouleau, gramine, olivier] |
268+
max %}
269+
270+
{% set max_labels = [] %}
271+
272+
{% if ambroisie == max_value %}{% set max_labels = max_labels + ['Ambroisie']
273+
%}{% endif %} {% if armoise == max_value %}{% set max_labels = max_labels +
274+
['Armoise'] %}{% endif %} {% if aulne == max_value %}{% set max_labels =
275+
max_labels + ['Aulne'] %}{% endif %} {% if bouleau == max_value %}{% set
276+
max_labels = max_labels + ['Bouleau'] %}{% endif %} {% if gramine == max_value
277+
%}{% set max_labels = max_labels + ['Graminées'] %}{% endif %} {% if olivier
278+
== max_value %}{% set max_labels = max_labels + ['Olivier'] %}{% endif %}
279+
280+
{{ max_labels | join(', ') }}
281+
```

img/badge.png

4.69 KB
Loading

0 commit comments

Comments
 (0)