Skip to content

French

Jump to bottom
thetrueavatar edited this page Nov 9, 2018 · 11 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

L'api nécessite que le composant php-curl soit installé. Sur un Raspberry il suffit d'exécuter la commande:

sudo apt-get install php-curl

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.

Désormais la documentation des méthodes est générée sur base du code sur a page: Viessmann Api 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.
  • getRoomTemperature : renvoie la température de la sonde intérieure de la pièce
  • getHotWaterStorageTemperature: renvoie la température du ballon d'eau chaude

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.4-SNAPSHOT.phar):

<?php
include 'phar://' . __DIR__ . '/Viessmann-Api-0.4-SNAPSHOT.phar/index.php';

use Viessmann\API\{ViessmannAPI, ViessmannApiException};

$credentials = file(__DIR__."/credentials.properties");
$params = [
    "user" => trim("$credentials[0]", "\n"),
    "pwd" => trim("$credentials[1]", "\n"),
    "deviceId" => "0",
    "circuitId"=>"0"
];
try {
$viessmannApi = new ViessmannAPI($params);
} catch (ViessmannApiException $e) {
    echo $e->getMessage();
    exit();
}

Pour changer de version, il suffit de changer la version du phar dans l'include. On peut passer le deviceId et le circuitId lors de la création de l'API. En faisant, ça tous les appels sur l'appel utiliseronts cette valeur par défaut. Il est néanmoins possible désormais de surcharger le circuitId pour chaque appel. Exemple: $viessmannApi->getRoomTemperature(2) forcera l'appel sur le circuit 2. Voici un Main.php montrant une liste de méthodes:

<?php
include __DIR__.'/bootstrap.php';

use Viessmann\API\ViessmannFeature;

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->getEcoProgramTemperature() . "\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 "Température eau chaude " . $viessmannApi->getHotWaterStorageTemperature() . "\n";
echo "Appelle resources " . $viessmannApi->getRawJsonData(ViessmannFeature::HEATING_CIRCUITS_0_OPERATING_PROGRAMS_ACTIVE) . "\n";

Liste de feature découverte dans l'application ViCare app disponible sous forme de constante dans ViessmannFeature.php

const GATEWAY_BMU = "gateway.bmu";
const GATEWAY_DEVICES = "gateway.devices";
const GATEWAY_FIRMWARE = "gateway.firmware";
const GATEWAY_LOGLEVEL = "gateway.logLevel";
const GATEWAY = "gateway";
const GATEWAY_STATUS = "gateway.status";
const GATEWAY_WIFI = "gateway.wifi";
const HEATING_BOILER_SENSORS = "heating.boiler.sensors";
const HEATING_BOILER_SENSORS_TEMPERATURE_COMMONSUPPLY = "heating.boiler.sensors.temperature.commonSupply";
const HEATING_BOILER_SENSORS_TEMPERATURE_MAIN = "heating.boiler.sensors.temperature.main";
const HEATING_BOILER_SERIAL = "heating.boiler.serial";
const HEATING_BOILER = "heating.boiler";
const HEATING_BOILER_TEMPERATURE = "heating.boiler.temperature";
const HEATING_BURNER_AUTOMATIC = "heating.burner.automatic";
const HEATING_BURNER_CURRENT_POWER = "heating.burner.current.power";
const HEATING_BURNER_MODULATION = "heating.burner.modulation";
const HEATING_BURNER = "heating.burner";
const HEATING_BURNER_STATISTICS = "heating.burner.statistics";
const HEATING_CIRCUITS_0_CIRCULATION_PUMP = "heating.circuits.0.circulation.pump";
const HEATING_CIRCUITS_0_CIRCULATION_SCHEDULE = "heating.circuits.0.circulation.schedule";
const HEATING_CIRCUITS_0_CIRCULATION = "heating.circuits.0.circulation";
const HEATING_CIRCUITS_0_DHW_SCHEDULE = "heating.circuits.0.dhw.schedule";
const HEATING_CIRCUITS_0_DHW = "heating.circuits.0.dhw";
const HEATING_CIRCUITS_0_FROSTPROTECTION = "heating.circuits.0.frostprotection";
const HEATING_CIRCUITS_0_HEATING_CURVE = "heating.circuits.0.heating.curve";
const HEATING_CIRCUITS_0_HEATING_SCHEDULE = "heating.circuits.0.heating.schedule";
const HEATING_CIRCUITS_0_HEATING = "heating.circuits.0.heating";
const HEATING_CIRCUITS_0_OPERATING_MODES_ACTIVE = "heating.circuits.0.operating.modes.active";
const HEATING_CIRCUITS_0_OPERATING_MODES_DHW = "heating.circuits.0.operating.modes.dhw";
const HEATING_CIRCUITS_0_OPERATING_MODES_DHWANDHEATING = "heating.circuits.0.operating.modes.dhwAndHeating";
const HEATING_CIRCUITS_0_OPERATING_MODES_FORCEDNORMAL = "heating.circuits.0.operating.modes.forcedNormal";
const HEATING_CIRCUITS_0_OPERATING_MODES_FORCEDREDUCED = "heating.circuits.0.operating.modes.forcedReduced";
const HEATING_CIRCUITS_0_OPERATING_MODES = "heating.circuits.0.operating.modes";
const HEATING_CIRCUITS_0_OPERATING_MODES_STANDBY = "heating.circuits.0.operating.modes.standby";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_ACTIVE = "heating.circuits.0.operating.programs.active";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_COMFORT = "heating.circuits.0.operating.programs.comfort";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_ECO = "heating.circuits.0.operating.programs.eco";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_EXTERNAL = "heating.circuits.0.operating.programs.external";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_HOLIDAY = "heating.circuits.0.operating.programs.holiday";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_NORMAL = "heating.circuits.0.operating.programs.normal";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_REDUCED = "heating.circuits.0.operating.programs.reduced";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS = "heating.circuits.0.operating.programs";
const HEATING_CIRCUITS_0_OPERATING_PROGRAMS_STANDBY = "heating.circuits.0.operating.programs.standby";
const HEATING_CIRCUITS_0_OPERATING = "heating.circuits.0.operating";
const HEATING_CIRCUITS_0_SENSORS = "heating.circuits.0.sensors";
const HEATING_CIRCUITS_0_SENSORS_TEMPERATURE_ROOM = "heating.circuits.0.sensors.temperature.room";
const HEATING_CIRCUITS_0_SENSORS_TEMPERATURE = "heating.circuits.0.sensors.temperature";
const HEATING_CIRCUITS_0_SENSORS_TEMPERATURE_SUPPLY = "heating.circuits.0.sensors.temperature.supply";
const HEATING_CIRCUITS_0 = "heating.circuits.0";
const HEATING_CIRCUITS_1_CIRCULATION_PUMP = "heating.circuits.1.circulation.pump";
const HEATING_CIRCUITS_1_CIRCULATION_SCHEDULE = "heating.circuits.1.circulation.schedule";
const HEATING_CIRCUITS_1_CIRCULATION = "heating.circuits.1.circulation";
const HEATING_CIRCUITS_1_DHW_SCHEDULE = "heating.circuits.1.dhw.schedule";
const HEATING_CIRCUITS_1_DHW = "heating.circuits.1.dhw";
const HEATING_CIRCUITS_1_FROSTPROTECTION = "heating.circuits.1.frostprotection";
const HEATING_CIRCUITS_1_HEATING_CURVE = "heating.circuits.1.heating.curve";
const HEATING_CIRCUITS_1_HEATING_SCHEDULE = "heating.circuits.1.heating.schedule";
const HEATING_CIRCUITS_1_HEATING = "heating.circuits.1.heating";
const HEATING_CIRCUITS_1_OPERATING_MODES_ACTIVE = "heating.circuits.1.operating.modes.active";
const HEATING_CIRCUITS_1_OPERATING_MODES_DHW = "heating.circuits.1.operating.modes.dhw";
const HEATING_CIRCUITS_1_OPERATING_MODES_DHWANDHEATING = "heating.circuits.1.operating.modes.dhwAndHeating";
const HEATING_CIRCUITS_1_OPERATING_MODES_FORCEDNORMAL = "heating.circuits.1.operating.modes.forcedNormal";
const HEATING_CIRCUITS_1_OPERATING_MODES_FORCEDREDUCED = "heating.circuits.1.operating.modes.forcedReduced";
const HEATING_CIRCUITS_1_OPERATING_MODES = "heating.circuits.1.operating.modes";
const HEATING_CIRCUITS_1_OPERATING_MODES_STANDBY = "heating.circuits.1.operating.modes.standby";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_ACTIVE = "heating.circuits.1.operating.programs.active";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_COMFORT = "heating.circuits.1.operating.programs.comfort";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_ECO = "heating.circuits.1.operating.programs.eco";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_EXTERNAL = "heating.circuits.1.operating.programs.external";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_HOLIDAY = "heating.circuits.1.operating.programs.holiday";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_NORMAL = "heating.circuits.1.operating.programs.normal";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_REDUCED = "heating.circuits.1.operating.programs.reduced";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS = "heating.circuits.1.operating.programs";
const HEATING_CIRCUITS_1_OPERATING_PROGRAMS_STANDBY = "heating.circuits.1.operating.programs.standby";
const HEATING_CIRCUITS_1_OPERATING = "heating.circuits.1.operating";
const HEATING_CIRCUITS_1_SENSORS = "heating.circuits.1.sensors";
const HEATING_CIRCUITS_1_SENSORS_TEMPERATURE_ROOM = "heating.circuits.1.sensors.temperature.room";
const HEATING_CIRCUITS_1_SENSORS_TEMPERATURE = "heating.circuits.1.sensors.temperature";
const HEATING_CIRCUITS_1_SENSORS_TEMPERATURE_SUPPLY = "heating.circuits.1.sensors.temperature.supply";
const HEATING_CIRCUITS_1 = "heating.circuits.1";
const HEATING_CIRCUITS = "heating.circuits";
const HEATING_CONTROLLER_SERIAL = "heating.controller.serial";
const HEATING_DEVICE = "heating.device";
const HEATING_DEVICE_TIME_OFFSET = "heating.device.time.offset";
const HEATING_DEVICE_TIME = "heating.device.time";
const HEATING_DHW_CHARGING_LEVEL = "heating.dhw.charging.level";
const HEATING_DHW_CHARGING = "heating.dhw.charging";
const HEATING_DHW_ONETIMECHARGE = "heating.dhw.oneTimeCharge";
const HEATING_DHW_PUMPS_CIRCULATION = "heating.dhw.pumps.circulation";
const HEATING_DHW_PUMPS_PRIMARY = "heating.dhw.pumps.primary";
const HEATING_DHW_SCHEDULE = "heating.dhw.schedule";
const HEATING_DHW_SENSORS = "heating.dhw.sensors";
const HEATING_DHW_SENSORS_TEMPERATURE_HOTWATERSTORAGE = "heating.dhw.sensors.temperature.hotWaterStorage";
const HEATING_DHW_SENSORS_TEMPERATURE_OUTLET = "heating.dhw.sensors.temperature.outlet";
const HEATING_DHW = "heating.dhw";
const HEATING_DHW_TEMPERATURE = "heating.dhw.temperature";
const HEATING_ERRORS_ACTIVE = "heating.errors.active";
const HEATING_ERRORS_HISTORY = "heating.errors.history";
const HEATING_ERRORS = "heating.errors";
const HEATING_GAS_CONSUMPTION_DHW = "heating.gas.consumption.dhw";
const HEATING_GAS_CONSUMPTION_HEATING = "heating.gas.consumption.heating";
const HEATING_SENSORS = "heating.sensors";
const HEATING_SENSORS_TEMPERATURE_OUTSIDE = "heating.sensors.temperature.outside";
const HEATING_SENSORS_TEMPERATURE = "heating.sensors.temperature";
const HEATING_SERVICE = "heating.service";
const HEATING = "heating";
Clone this wiki locally