Skip to content

How to add you own feature to the api

Jump to bottom
thetrueavatar edited this page Nov 12, 2019 · 30 revisions

How to work with my github

  • Do a fork of my github project. You'll do your update in this fork. Once you have done your dev, then create a pull request. This request will ask me to merge your change with the main code. I will do a review before merging.
  • I'm working on the develop branch. Master is for release.
  • The new method have to be added in the ViessmannAPI.php file
  • Feature have to be as constant in ViessmannFeature.php

How to implement data read

Basically there are 2 case:

  1. your feature has a digit (ex:heating.circuits.0.circulation.pump ). This means it depends of the circuitId. For this, I'm using this kind of :

    public function getCirculationPumpStatus($circuitId = NULL)
{
 return $this->getEntity($this->buildFeature($circuitId, self::CIRCULATION_PUMP))->getProperty("status")["value"];

    } the buildFeature private method will take the "heating.circuits", append the current circuitId(can be ovewritten throug param method) and at last add the CIRCULATION_PUMP constant="circulation.pump". This will provide you the heating.circuits.0.circulation.pump string. The getEntity method do the call with the provided feature, and convert the siren/json response into a Siren object. Most of the time, you just have to get the property (here it's status) and ask the value from it.

  2. You don't have any digit then you can just call directly the getEntity method on the feature. I add the feature directly as constant in ViessmannFeature:

    public function getOutsideTemperature(): string
 {
     return $this->getEntity(ViessmannFeature::HEATING_SENSORS_TEMPERATURE_OUTSIDE)->getProperty("value")["value"];
 }

  • To help you to know which property value to useyou can call the getRawJsonData on the feature which will show you the json response. For instance:

    <?php
 include __DIR__ . '/bootstrap.php';
 echo $viessmannApi->getRawJsonData(\Viessmann\API\ViessmannFeature::HEATING_SENSORS_TEMPERATURE_OUTSIDE);

    will give you something like:

          {
"links": [
  {
    "rel": [
      "self"
    ],
    "href": "https://api.viessmann-platform.io/operational-data/v1/installations/XX/gateways/YYY/devices/0/features/heating.sensors.temperature.outside"
  },
  {
    "rel": [
      "up"
    ],
    "href": "https://api.viessmann-platform.io/operational-data/v1/installations/X/gateways/Y/devices/0/features"
  },
  {
    "rel": [
      "http://schema.viessmann.com/link-relations#live-updates",
      "https://wiki.viessmann.com/display/VPL/Relations#Relations-live-updates"
    ],
    "href": "/operational-data/installations/X/gateways/X/devices/0/features/heating.sensors.temperature.outside"
  }
],
"class": [
  "heating.sensors.temperature.outside",
  "feature"
],
"properties": {
  "status": {
    "type": "string",
    "value": "connected"
  },
  "value": {
    "type": "number",
    "value": **6.5**
  }
},
"entities": [
  {
    "rel": [
      "http://schema.viessmann.com/link-relations#feature-meta-information",
      "https://wiki.viessmann.com/display/VPL/Relations#Relations-feature-meta-information",
      "https://wiki.viessmann.com/display/VPL/Amounts#Amounts-unique"
    ],
    "properties": {
      "apiVersion": 1,
      "isEnabled": true,
      "isReady": true,
      "gatewayId": "7571381753685105",
      "feature": "heating.sensors.temperature.outside",
      "uri": "/v1/gateways/7571381753685105/devices/0/features/heating.sensors.temperature.outside",
      "deviceId": "0",
      "timestamp": "2019-11-12T12:21:02.127Z"
    }
  }
],
"actions": []

    }

The interesting part it the property part which will give you information about what to specify in the getProperty method on the Entity object.

  • I use string as return value for single value, for status a bool is more appropriate. If you need to encode/decod string in json I'm using the json_encode and json_decode method from php. Don't forget to pass true as second parameter cause this parameter will tell the decoder to map the json string into an objet structure allowing you to navigate in this structure.

How to implement data write

For setter, it's a little bit more tricky. I usually do a get and have a look at the actions part on the feature which define the format of the data to send. For instance:

  public function setCurve($shift, $slope, $circuitId = NULL)
  {
    $this->setRawJsonData($this->buildFeature($circuitId, self::HEATING_CURVE), "setCurve", "{\"shift\":" . $shift . ",\"slope\":" . $slope . "}");
  }

the "setCurve" and format "{shift:value,slope:value} is coming from the actions part from the get on heating.circuits.0.heating.curve:

"actions": [
{
  "method": "POST",
  "isExecutable": true,
  "href": "https://api.viessmann-platform.io/operational-data/v1/installations/55994/gateways/7571381753685105/devices/0/features/heating.circuits.0.heating.curve/setCurve",
  "name": "setCurve",
  "title": "setCurve",
  "fields": [
    {
      "name": "slope",
      "required": true,
      "type": "number",
      "min": 0.2,
      "max": 3.5,
      "stepping": 0.1
    },
    {
      "name": "shift",
      "required": true,
      "type": "number",
      "min": -13,
      "max": 40,
      "stepping": 1
    }
  ],
  "type": "application/json"
}
]

Clone this wiki locally