How to add you own feature to the api

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

How to implement data read

Basically there are 2 case:

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

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

   } This buildFeature will take the "heating.circuits", append the current circuitId(can be ovewritten throug param method) and at last add the circulation.pump(it's a constant of ViessmanAPI). This will provide you the heating.circuits.0.circulation.pump string. The getEntity method do the call, 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 cifer then you can just call directly the getEntity method on the feature. I add the feature 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 value you have to get you 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.

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"
}

]