Skip to content

Home

Jump to bottom
thetrueavatar edited this page Sep 16, 2018 · 33 revisions

Viessman-Api

Généralités

Le code a été développé en php 7. Le git suit le principe de GitFlow:

  • La branche master contiendra les livraison(0.1,0.2,0.3,...)
  • La branche develop contiendra les développement(feature) en cours finalisés et la version sera suffixée par SNAPSHOT
  • Les branches feature/xxx contiendront les feature en cours de développement. Il se peut que je ne les commit pas toutes et les mettent directement dans develop.

Les dépendances sont gérées via composer. Le client Oauth est implémenté à l'aide la librairie PHPoAuthLib https://github.com/Lusitanian/PHPoAuthLib Le parsing Siren Json est fait avec siren-php https://github.com/tomphp/siren-php

Désormais, l'API est livrée sous la forme d'un seul fichier .phar(php archive) qu'on peut inclure directement dans un fichier php.

Pour compiler le code en phar:

Un script shell existe dans script/createPhar.sh il lance la commande php -d phar.readonly=0 phar-builder.phar package composer.json dans le répertoire racine. Les paramètres du phar-builder.phar sont défini dans le composer.json: "extra": { "phar-builder": { "compression": "GZip", "name": "Viessmann-Api-0.2.phar", "output-dir": "./example", "entry-point": "./index.php", "include": "php", "include-dev": false, "skip-shebang":false } } Vous aurez alors un nouveau phar dans le répertoire bin du projet.

Exécution

Le fichier php example/Main.php montre un simple exemple d'appel. Le point crucial dans l'utilisation de l'api est la ligne include 'phar://../bin/Viessmann-Api-0.1-SNAPSHOT.phar/index.php' . Ca permet d'importer toute l'api. Il est obligatoire de mettre /index.php à la fin car ça inclus l'autoloading.

Pour utiliser l'api, il suffit d'instancier ViessmannAPI avec un tableau de paramètres contenant:

  • user: le username viessmann
  • pwd: le password viessmann
  • uri: l'uri de retour après Oauth. En pratique nous ne l'utilisons pas. J'envisage d'enlever ce paramètre. Tout le reste de la partie Oauth se fait de façon transparente à l'instanciation de l'api. Il suffit d'appeler les méthodes sur l'api. Les getter renvoie les valeurs, les setter les écrivents.

La méthode getFeatures() permet de récupérer le tableau de toutes les features en json.

La méthode getRawJsonData renvoie le json/siren directement de la feature passée en paramètre. La méthode setRawJsonData permet de changer la valeur d'une feature. Il faut lui passer la feature, l'action possible sur cette feature, et un json contenant la donnée à écrire. J'ai ajouté des constantes pour les features courrantes(voir code en fin de page). Les méthodes getRawJsonData et setRawJsonData sont génériques. J'ai déjà implémenté quelques méthodes pour simplifier les appels:

  • getInstallationId: renvoie le numéro de l'installation
  • getGatewayId: renvoie le numéro du gateway
  • getFeatures: renvoie toutes les features en format json
  • getOutsideTemperature: renvoie la température extérieure
  • getBoilerTemperature: renvoie la température de la chaudière
  • getSlope: renvoie la pente de la chaudière
  • getShift: renvoie le parallèle de la chaudière
  • getActiveMode: renvoie le mode actif(DHW, Chauffage,Chauffage+DHW,...)
  • getActiveProgram: renvoie le program actif(normal, réduit,...)
  • isHeatingBurnerActive: renvoie si le brûleur est actif
  • isDhwModeActive: renvoie true/false si le mode eau chaude sanitaire est actif/inactif
  • getComfortProgramTemperature: renvoie la température configurée de confort
  • getEchoProgramTemperature: renvoie la température configurée du mode écho
  • getExternalProgramTemperature: renvoie la température configurée du programme extérieur
  • getNormalProgramTemperature: renvoie la température configurée du programme normal
  • getReducedProgramTemperature: renvoie la température configurée du programme réduit
  • getSupplyProgramTemperature: renvoie la température configurée du programme "Supply'
  • isInStandbyMode: renvoie true/false si on est ou pas en standby mode
  • setDhwTemperature : défini une nouvelle température pour l'ECS.

Voici des exemples d'appels. J'ai fait un fichier commun(bootstraph.php) qui va chercher le user/pwd dans un fichier credentials.properties et l'include du phar(içi Viessmann-Api-0.3-SNAPSHOT.phar):

<?php
include 'phar://'.__DIR__.'/Viessmann-Api-0.3-SNAPSHOT.phar/index.php';
use Viessmann\API\ViessmannAPI;
$credentials = file(__DIR__."/credentials.properties");
$params = [
    "user" => trim("$credentials[0]", "\n"),
    "pwd" => trim("$credentials[1]", "\n"),
    "uri" => "vicare://oauth-callback/everest"
];
$viessmannApi = new ViessmannAPI($params);

Pour changer de version, il suffit de changer la version du phar dans l'include. Voici un Main.php montrant une liste de méthodes:

<?php
include __DIR__.'/bootstrap.php';
echo $viessmannApi->getFeatures();
echo "Température extérieure " . $viessmannApi->getOutsideTemperature() . "\n";
echo "Température boiler " . $viessmannApi->getBoilerTemperature() . "\n";
echo "Pente " . $viessmannApi->getSlope() . "\n";
echo "Parallèle " . $viessmannApi->getShift() . "\n";
echo "Mode chaudière " . $viessmannApi->getActiveMode() . "\n";
echo "Programme actif " . $viessmannApi->getActiveProgram() . "\n";
echo "Is Heating Burner active ? " . $viessmannApi->isHeatingBurnerActive() . "\n";//in php false bool is converted into empty string
echo "Is Dhw mode active ? " . $viessmannApi->isDhwModeActive() . "\n";
echo "Température de confort " . $viessmannApi->getComfortProgramTemperature() . "\n";
echo "Température écho " . $viessmannApi->getEchoProgramTemperature() . "\n";
echo "Température externe " . $viessmannApi->getExternalProgramTemperature() . "\n";
echo "Température réduit " . $viessmannApi->getReducedProgramTemperature() . "\n";
echo "Température supply " . $viessmannApi->getSupplyProgramTemperature() . "\n";
echo "Est en veille ? " . $viessmannApi->isInStandbyMode() . "\n";
echo "Appelle resources " . $viessmannApi->getRawJsonData(ViessmannAPI::HEATING_PROGRAM_ACTIVE). "\n";
#echo "écriture température ecs avec json ".$viessmanApi->setRawJsonData(ViessmannAPI::HEATING_DWH_TEMPERATURE,"setTargetTemperature","{\"temperature\":60.0}"). "\n";
#echo "écriture température ecs ".$viessmanApi->setDhwTemperature("58.0"). "\n";

Liste des constantes passables à getRawData:

const BOILER_TEMP="heating.boiler.sensors.temperature.main";
const HEATING_BURNER="heating.burner";
const HEATING_CIRCUITS="heating.circuits";
const HEATING_CIRCUITS_0="heating.circuits.0";
const HEATING_CURVE="heating.circuits.0.heating.curve";
const HEATING_OPERATING_MODES="heating.circuits.0.operating.modes.active";
const HEATING_DWH_MODE="heating.circuits.0.operating.modes.dhw";
const HEATING_DWH_AND_HEATING_MODE="heating.circuits.0.operating.modes.dhwAndHeating";
const HEATING_FORCED_NORMAL_MODE="heating.circuits.0.operating.modes.forcedNormal";
const HEATING_FORCED_REDUCTED_MODE="heating.circuits.0.operating.modes.forcedReduced";
const HEATING_STANDY_MODE="heating.circuits.0.operating.modes.standby";
const HEATING_PROGRAM_ACTIVE="heating.circuits.0.operating.programs.active";
const HEATING_PROGRAM_COMFORT="heating.circuits.0.operating.programs.comfort";
const HEATING_PROGRAM_ECHO="heating.circuits.0.operating.programs.eco";
const HEATING_PROGRAM_EXTERNAL="heating.circuits.0.operating.programs.external";
const HEATING_PROGRAM_NORMAL="heating.circuits.0.operating.programs.normal";
const HEATING_PROGRAM_REDUCED="heating.circuits.0.operating.programs.reduced";
const HEATING_PROGRAM_STANDBY="heating.circuits.0.operating.programs.standby";
const HEATING_PROGRAM_SUPLY="heating.circuits.0.sensors.temperature.supply";
const HEATING_TIME_OFFSET="heating.device.time.offset";
const HEATING_DWH="heating.dhw";
const HEATING_CIRCUITS_1_DHW="heating.circuits.1.dhw";
const HEATING_DWH_TEMPERATURE="heating.dhw.temperature";
const HEATING_DWH_SENSORS="heating.dhw.sensors";
const HEATING_DWH_SENSORS_TEMPERATURE="heating.dhw.sensors.temperature";
const HEATING_DWH_SCHEDULE="heating.dhw.schedule";
const HEATING_DWH_TEMPERATURE_HOTWATER_STORAGE="heating.dhw.sensors.temperature.hotWaterStorage";
const HEATING_DWH_TEMPERATURE_OUTLET="heating.dhw.sensors.temperature.outlet";
const HEATING_GAS_CONSUMPTION_DHW="heating.gas.consumption.dhw";
const HEATING_TEMP_OUTSIDE="heating.sensors.temperature.outside";
const HEATING_SENSORS_TEMPERATURE="heating.sensors.temperature";
const HEATING_TIMEBASE="heating.service.timeBased";
const HEATING_SENSORS="heating.sensors";
const GATEWAY_DEVICES="gateway.devices";
Clone this wiki locally