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.

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

]