PLugin “volvocars” pour Jeedom

Le plugin volvocars permet à Jeedom d’interagir avec votre véhicule Volvo en utilisants les API volvocars.

Merci à @Xav-74, Je me suis beaucoup inspiré de son plugin My BMW pour le widwet et le panel.

Principe

Ce plugin interagit avec les API Volvocars au travers le cloud, Par conséquent, ce plugins nécessite une connection internet. Il faut aussi que votre véhicule soit accessible dans l’app Volvo Cars.

La documentation des APIs indique qu’elles sont disponnibles pour tous les modèles entre de 2015 à 2022. Mais il semble que cette documentation ne soit pas à jour et que les modèles post 2022 sont aussi disponibles via ces API. Le plugin a été dévoloppé en utilisant un XC40 électrique de 2023.

Modèles compatibles

• Modèles confirmés compatibles avec le plugin:
  • XC40 électrique (2023)
• Modèles confirmés partiellement compatibles avec le plugin:
• Modèles confirmés incompatibles avec le plugin:

Les clés API vcc

Outre le compte Volvo ID que vous utilisez dnas l’app volvocars, vous aurez besoin d’une clé API vcc personnelle.

Vous devez générer une Clé API vcc (VCC API Key) sur le site https://developer.volvocars.com/ en suivant cette procédure:

1. Cliquez sur Sign up:
   
2. Selectionnez le compte qui sera associé à votre nouveau compte developper.volvocars:
   
3. Saisissez votre login/password pour le site sélectionné au point précédent
   
4. Cliquez sur votre nom de login puis sur Your API applications
   
5. Saisissez un nom pour l’application que vous allez créer puis cliquez sur Create. Si vous avez plusieurs instances Jeedom, il est conseillé de créer une application pour chaque instance dans laquelle le plugon sera installé:
   
6. Votre nouvelle application est créée avec un couple de VCC API Keys. Vous pourrez toujours revenir sur cette page pour récupérer votre clé.
   

Installation et configuration du plugin

Installation du plugin

Le plugin s’installe de manière standard depuis le market de Jeedom.

Si l’installation des dépendances n’a pas été lancée automatiquement après l’installation du plugin, lancez là manuellement. Une fois les dépendances installées, assurez-vous que le daemon est démarré.

Configuration du plugin

• Clé VCC API

  Saisissez la clé VCC-API-key que vous avez généré sur le site developer.volvocars.com.

• Utiliser le widget du plugin

  Sélectionnez cette option pour utiliser le widget du plugin dans les dashboards.

• Commandes à créer pour les ouvrants

  Les API volvocars retournent une information de type text pour l’état des ouvrants. Ce texte est enregistré dans une commande *_state de l’équipement.
  Des commandes binaires *_open et *_closed seront également créées si l’option Ouvert ou Fermé est activée.

  Les commandes *_open ou *_closed existantes ne sont pas supprimées lorsque l’option correspondante est désactivée.

Une fois le plugin installé, il faut créer un account.

Les accounts

Cliquer sur Ajouter

Saisir le nom du compte puis cliquer sur OK

Saisir le login et le password du compte VolvoId puis cliquer sur OK

Saisir le code que Volvo vous a envoyé par email puis cliquer sur OK.

La saisie du code est nécessaire pour l’obtention d’un token qui sera utilisé par le plugin pour authentifier ses accès aux API Volvocars. Ce token sera automatiquement renouvelé avant son expiration.

Le token pourra être perdu si

• Les véhicules associés à l’account sont tous désactivés durant une certaine période.
• Le plugin est désactivé durant plus d’un certain temps.
• Jeedom est arrêté durant plus d’un certain temps.
• Une sauvegarde de Jeedom est restaurée.

Dans ces cas, il faut ouvrir l’édition de l’account et le sauvegarder. Ceci relancera la procédure pour saisir un nouveau code envoyé par email puis obtenir un nouveau token.

Selon la documentation des APIs, un token expiré peut être renouvelé automatiquement jusqu’à 7 jours après sont expiration. Mais je n’ai pas pu le vérifier. Vu que les tokens ont un validité de 30 minutes et sont renouvelés 15 minutes avant leur expiration, un arrêt de moins de 15 minute ne devrait as avoir de conséquence.

Les véhicules

Les équipements jeedom pour les véhicules associés à un account sont automatiquement créés (ou mis à jour) lors de la synchronisation de l’account

Synchronisation d’un account (création des véhicules)

• Cliquer sure le bouton Synchronisation
• Sélectionner l’account à synchroniser

• Le nouveau véhicule est ajouté à la liste des véhicules

  :bulb: Dans certains cas, le site fournisseur d’image peut bloquer les accès effectués par un script. Dans ce cas, le logo Volvo sera affiché à la place de l’image du véhicule. L’image du véhicule devra être chargée manuellement depuis la page de configuration du véhicule.

Configuration du véhicule

• Paramètres généraux

  Ces paramètres sont les paramètres standards des équipements Jeedom. Ils ne seront pas détaillés ici.

• Paramètres du véhicule

  Ces paramètres sont renseignés automatiquement lors de la synchronisation de l’account. D’édition des ces paramètres est désactivée par défaut car ils ne devraient pas être modifiés par l’utilisateurs.

  En cas de nécessité, il est possible de débloquer l’édition de ces paramèetres en cliquant sur le bouton Editer

• Paramètres d’alertes

  • Automomie électriques
    La valeur de la commande al_electricAutonomy passe à 1 lorsque l’autonomie électrique est inférieur à cette limite.

  • Automomie thermique
    La valeur de la commande al_fuelAutonomy passe à 1 lorsque l’autonomie du moteur themique est inférieur à cette limite.

• Paramètres de localisation

  Les coordonnées GPS de deux site peuvent être configurée. Deux commandes seront créées pour chacun de ces sites:

  • distanceSite# : Distance entre la site et la véhicule
  • presenceSite# : binaire qui indique est sur le site

  Les paramètres:

  • Nom
    Si l’on renomme un site les deux commandes associées seront aussi renommée si leurs noms contiennent l’ancien nom du site
  • Coordonées GPS
    Les coordonnées GPS du site
  • Distance max (en m)
    Distance maximum (en mètres) entre le véhicule et le site pour que le véhicule soit indiqué présent sur le site.
  • Récupérer coordonnées GPS
    Deux boutons permettant de renseigner automatiquement les coordonnées GPS du site:
    • Jeedom : Récupèere les coordonnées GPS de Jeedom qui ont été renseignées dans la config de Jeedom.
    • Véhicule : Récupère la position actuelle du véhicule

• Description

  Info libre

• Image

  Image du véhicule qui sera utilisée dans le panel. Si l’image du véhicule n’a pas pu être récupérée lors de la synchronisation de l’account, elle sera remplacée par un logo Volvo et un bouton Récupérer une image du véhicule (voir plus bas pour la procédure de récupération manuelle de l’image).

• Données brutes

  Ce bouton ouvre un popup avec les données tels qu’elles sont fournies par les API. Ces infomations peuvent être utiles pour analyse en cas de problème.

Récupération manuelle de l’image

• Si l’image du véhicule n’a pas pu être chargée, le logo Volvo et le bouton Récupérer une image du véhicule sont affichés:

  

• Cliquer sur le bouton Récupérer une image du véhicule
  • Le logo est remplacé par une image du véhicule
  • Le bouton Récupérer une image du véhicule n’est plus affiché:
  • Une zone est marquée pour y copier l’image du véhicule

  

• Utiliser le menu contextuel (PAS DE RACCOURCI CLAVIER!) pour copier l’image.

  

• Utiliser le menu contextuel (PAS DE RACCOURCI CLAVIER!) pour coller l’image dans la zone prévue à cet effet.

  

• L’image est envoyée au plugin

• La zone prévue pour la réception d’une copie de l’image n’est pla affichée.

  

Les commandes

Les actions

Le plugin peut envoyer au véhicule les commandes suivantes

• unlock
  Déverrouillage du véhicule
• lock
  Verrouillage du véhicule
• lockReduced
  Verrouillage avec le mode alarme réduit
• climStart
  Démarrage de la climatisation
• climStop
  Arrêt de la climatisation
• honk
  Klaxonne
• flash
  Les clignotants du véhicule clignotent.
• honk_flash
  Exécution simultanée des commandes honk et flash

Les commandes effectivement activées dans le plugin pour un véhicule dépendent des fonctionnalités du véhicule qui sont remontées par les API (endpoint commands).

Les infos

:bulb: Les commandes de type info ne sont pas créée lors de la création du véhicule. Elles sont créées dynamiquement après l’activation du véhicule en fonction de données reçues des API.

§ §

Nom	LogicalId	API endpoint	SousType	Valeurs/Unité	Description
GLOBALES
Disponibilité	availability	accessibility	texte	"AVAILABLE"	Le véhicule est connecté
				"UNAVALAIBLE"	Le véhicule est déconnecté
				"UNSPECIFIED"	Information indisponible
				"QUOTA_OUT"	Le quota d'appels API a été atteint
raison indisponibilité	unavailableReason	accessibility	texte	"NO_INTERNET"	Pas d'internet
				"POWER_SAVING_MODE"	Véhicule en mode veille
				"CAR_IN_USE"	Véhicule cours d'utilisation
				"UNSPECIFIED"	Information indisponible
				""	Le véhicule est disponible
odomètre	odometer	odometer	numérique	Km	Kilométrage du véhicule
service	service	diagnostics	texte	"NO_WARNING"	Pas de service à effectuer
				"REGULAR_MAINTENANCE_ALMOST_TIME_FOR_SERVICE"	Délai pour un service bientôt atteint
				"ENGINE_HOURS_ALMOST_TIME_FOR_SERVICE"	Temps de fonctionnement du moteur avant service bientôt écoulé
				"DISTANCE_DRIVEN_ALMOST_TIME_FOR_SERVICE"	Kilométrage pour un service bientôt atteint
				"REGULAR_MAINTENANCE_TIME_FOR_SERVICE"	Délai pour un service atteint
				"ENGINE_HOURS_TIME_FOR_SERVICE"	Temps de fonctionnement du moteur avant service écoulé
				"DISTANCE_DRIVEN_TIME_FOR_SERVICE"	Kilométrage pour un service atteint
				"REGULAR_MAINTENANCE_OVERDUE_FOR_SERVICE"	Délai pour un service dépassé
				"ENGINE_HOURS_OVERDUE_FOR_SERVICE"	Temps de fonctionnement du moteur avant service dépassé
				"DISTANCE_DRIVEN_OVERDUE_FOR_SERVICE."	Kilométrage pour un service dépassé
				"UNKNOWN_WARNING"	Alerte inconnue
				"UNSPECIFIED"	indéterminé
Raison du service	serviceTrigger	diagnostics	texte	CALENDAR_TIME	Délai depuis dernier service écoulé
				"DISTANCE"	Distance parcourue depuis dernier service
				"ENGIME_HOURS"	Temps de fonctionnement du moteur
				"UNSPECIFIED"	Non spécifié
				"UNKNOWN"	Inconnu
Heures moteur avant service	engineHoursToService	diagnostics	numérique	Heures	Temps de fonctionnement du moteur avant le prochain service
Distance avant service	distanceToService	diagnostics	numérique	Kilomètres	Distance avant le prochain service
Jours avant service	timeToService	diagnostics	numérique	Jours	Nombre de jours avec le service. L'API volvocars retourne soit un nombre de jours soit un nombre de mois. Le plugin convertit le nombre de mois en nombre de jour. Il peut donc y avoir une erreur de 30 jours.
LOCALISATION
position	position	location	coordonnées GPS	<lattitude>,<longitude>	position du véhicule
distance <nom_site_1>	distanceSite1		numérique	mètre	Distance entre le véhicule et le site 1
présence <nom_site_1>	presenceSite1		binaire	0	Le véhicule n'est pas sur le site 1
				1	Le véhicule est sur le site 1
distance <nom_site_2>	distanceSite2		numérique	mètre	Distance entre le véhicule et le site 1
présence <nom_site_2>	presenceSite2		binaire	0	Le véhicule n'est pas sur le site 2
				1	Le véhicule est sur le site 2
OUVRANTS
Verrouillé	locked	doors	text	LOCKED	Véhicule Verrouiller
				UNLOCKED	Véhicule Déverrouiller
				UNSPECIFIED	Information indisponible
état porte avant gauche état porte avant droite état porte arrière gauche état porte arrière droite état capot état hayon état trappe	doorFlState doorFrState doorRlState doorRrState hoodState tailState tankState	doors	texte	CLOSED	fermé
				AJAR	entre-ouvert
				OPEN	ouvert
état vitre avant gauche état vitre avant droite état vitre arrière gauche état vitre arrière droite état toit	winFlState winFrState winRlState winRrState roofState	windows
				UNSPECIFIED	Information indisponible
porte avant gauche ouverte porte avant droite ouverte porte arrière gauche ouverte porte arrière droite ouverte vitre avant gauche ouverte vitre avant droite ouverte vitre arrière gauche ouverte vitre arrière droite ouverte capot ouvert toit ouvert hayon ouvert trappe ouverte	doorFlOpen doorFrOpen doorRlOpen doorRrOpen winFlOpen winFrOpen winRlOpen winRrOpen hoodOpen roofOpen tailOpen tankOpen		binaire	0	pas ouvert
				1	ouvert
porte avant gauche fermée porte avant droite fermée porte arrière gauche fermée porte arrière droite fermée vitre avant gauche fermée vitre avant droite fermée vitre arrière gauche fermée vitre arrière droite fermée capot fermé toit fermé hayon fermé trappe fermée	doorFlClosed doorFrClosed doorRlClosed doorRrClosed winFlClosed winFrClosed winRlClosed winRrClosed hoodClosed roofClosed tailClosed tankClosed		binaire	0	pas fermé
				1	ouvert
Portes fermées	allDoorsClosed		binaire	0	une porte, le capot ou le coffre n'est pas fermé
				1	Toutes les portes ainsi que le capot et le coffre sont fermés
Fenêtres fermées	allWinsClosed		binaire	0	Une fenêtre ou le toit n'est pas fermé
				1	Toutes les fenêtres ainsi que le toit sont fermés
MOTEUR THERMIQUE
moteur en service	engineON	engine_status	binaire	0	moteur à l'arrêt
				1	moteur en marche
consommation carburant	consoFuel	statistics	numérique	l/100Km	consommation moyenne calculée par le véhicule
consommation carburant (trajet)	consoFuelTrip	statistics	numérique	l/100Km	consommation moyenne depuis de début du trajet automtique
carburant	fuelAmount	fuel	numérique	l	Quantité de carburant restant
autonomie thermique	fuelAutonomy	statistics	numérique	Km	Autonomie avec le carburant restant
Autonomie fuel faible	al_fuelAutonomy		binaire	0	Autonomie fuel suffisante
				1	Autonomie fuel faible
niveau d'huile	oilLevel	engine_dignostics	texte	"UNSPECIFIED"	Information indisponible
				"NO_WARNING"	Niveau normal
				"SERVICE_REQUIRED"	Nécessite un service
				"TOO_LOW"	Niveau bas
				"TOO_HIGH"	Niveau haut
alerte huile	al_oil		binaire	0	Le niveau d'huile est normal
				1	Alerte (voir la commande oil_level pour plus de détails)
niveau liquide de refroidissement	coolantLevel	engine_dignostics	texte	"UNSPECIFIED"	Information indisponible
				"NO_WARNING"	Niveau normal
				"TOO_LOW"	Niveau bas
alerte liquide de refroidissement	al_coolant		binaire	0	Le niveau est normal
				1	Alerte (voir la commande coolant_level pour plus de détails)
MOTEUR ELECTRIQUE
consommation électrique	consoElectric	statistics	numérique	kW/100Km	Consomation moyenne calculé par le véhicule
Autonomie électrique	electricAutonomy	statistics	numérique	Km	Autonomie avec la charge restante
Autonomie électrique faible	al_electricAutonomy		binaire	0	Autonomie électrique suffisante
				1	Autonomie électrique faible
niveau charge batterie	batteryLevel	recharge_status	numérique	%	Pourcentage de charge de la batterie
Etat de la charge	chargingStatus	recharge_status	texte	"CHARGING_SYSTEM_CHARGING"	Recharge en cours
				"CHARGING_SYSTEM_IDLE"	Système de recharge en attente
				"CHARGING_SYSTEM_DONE"	Recharge terminée
				"CHARGING_SYSTEM_FAULT"	Système de recharge en erreur
				"CHARGING_SYSTEM_SCHEDULED"	Recharge programmée
				"CHARGING_SYSTEM_UNSPECIFIED"	Etat indéterminé
Temps de charge restant	chargingRemainingTime	recharge_status	numérique	minutes	Temps estimé avant fin de recharge
Heure fin de charge	chargingEndTime		texte	jj HH:MM	Heure de fin de charge prévue
Etat de la prise	connectorStatus	recharge_status	texte	"CONNECTION_STATUS_CONNECTED_AC"	Branchée à une borne AC
				"CONNECTION_STATUS_CONNECTED_DC"	Branchée à une borne DC
				"CONNECTION_STATUS_DISCONNECTED"	Débranchée
				"CONNECTION_STATUS_FAULT"	Prise en erreur
				"CONNECTION_STATUS_UNSPECIFIED"	Etat indéterminé
LAVE-VITRES
Niveau lave-vitres	washerFluidLevel	diagnostics	texte	"UNSPECIFIED"	Information indisponible
				"NO_WARNING"	Niveau normal
				"TOO_LOW"	Niveau bas
alerte lave-vitres	al_washerFluid	binaire	0	Le niveau est normal
			1	Alerte (voir la commande washer_fluid_level pour plus de détails)
LIQUIDE DE FREIN
Niveau liquide de frein	brakeFluidLevel	brakes	texte	"UNSPECIFIED"	Information indisponible
				"NO_WARNING"	Niveau normal
				"TOO_LOW"	Niveau bas
alerte liquide de frein	al_brake_fluid	binaire	0	Le niveau est normal
			1	Alerte (voir la commande brake_fluid_fluid_level pour plus de détails)
PRESSION PNEUS
pneu avant gauche pneu avant droit pneu arrière gauche pneu arrière droit	tyreFl tyreFr tyreRl tyreRr	tyre	texte	"UNSPECIFIED"	Information indisponible
				"NO_WARNING"	Pression normale
				"VERY_LOW_PRESSURE"	Pression très basse
				"LOW_PRESSURE"	Pression basse
				"HIGH_PRESSURE"	Pression élevée
alerte pneus	al_tyre		binaire	0	Les pressions sont normales
				1	Alerte (voir les commandes tyre_* pour plus de détails)
ECLAIRAGES
feu frein gauche feu frein droite feu frein central feu jour gauche feu jour droit feux brouillard avant feux brouillard arrière feux détresse feu route gauche feu route droite feu croisement gauche feu croisement droite feu position avant gauche feu position avant droite feu position arrière gauche feu position arrière droit feu plaque feu recule feux latéraux clignotant avant gauche clignotant avant droit clignotant arrière gauche clignotant arrière droit	al_brakeLightL al_brakeLightR al_brakeLightC al_daytimeRunningLightL al_daytimeRunningLightR al_fogLightF al_fogLightR al_hazardLights al_highBeamL al_highBeamR al_lowBeamL al_lowBeamR al_positionLightFl al_positionLightFr al_positionLightRl al_positionLightRr al_registrationPlateLight al_reverseLights al_sideMarkLights al_turnIndicationFl al_turnIndicationFr al_turnIndicationRl al_turnIndicationRr	warnings	texte	"UNSPECIFIED"	Information indisponible
				"NO_WARNING"	Pas de défaut
				"FAILURE"	Défaut
alerte lampes	al_light		binaire	0	Pas de lampe défectueuse
				1	Défaut (voir les commandes de feux pour plus de détails)
PLUGIN
messages pour wigget	msg2wigget		texte	json	Messages pour le fonctionnement du widget du panel

Les endpoints des API volvocars

Ce plugin utilise trois APIs volvocars. Chacune de ces API donne accès à des endpoints qui fournissent chacun uni ensemble d’informations. Les tableaux des actions et des infos ci-dessus indiquent quel endpoint fourni l’information associée chacune des commandes info ou action du plugin.

Volvo limite le nombre d’accès quotidien aux APIs à 10’000 par clé VCC-API. Pour respecter cette limite tout en ayant des infos actualisées sans trop de délai, le plugin n’accède pas à tous les endpoints à la même fréquence. La position du vhéhicule est, par exemple, mise à jour chaque minute pour permettre une certaine réactivité lorsque le véhicule arrive au domicile alors que le niveau du liquide de frein ne l’est que toutes les 60 minutes.

Les endpoints

API	endpoint	fréquence	Nombre d'appels quotidien
			tout véhicule	moteur thermique	moteur électrique
Connected-vehicle	brakes	60 min.	24
	command-accessibility	5 min.	288
	commands1	0
	details1	0
	diagnostics	10 min.	144
	doors	2 min.	720
	engine	15 min.		96
	engine-status	5 min.		288
	fuel	30 min.		48
	odometer	15 min.	96
	statistics	10 min.	144
	tyres	30 min.	48
	vehicles1	0
	warnings	30 min.	48
	windows	2 min.	720
Location	location	1 min.	1'440
Energy	recharge-status	5 min.			288
Total			3672	432	288

¹ Endpoint appelé lors de la synchronisation d’un account.

Il y a donc:

• 4104 appels par jour pour un véhicule thermique.
• 3960 appels par jour pour un véhicule électrique.
• 4392 appels par jour pour un véhicule hybride.

A ceci, s’ajoutent les appels lors de l’envoi d’une commande, d’un refresh ou d’une synchronisation des véhicules associés à un compte.