Scripted devices via API anlegen

mohanisch

Hallo Luz,

ist es möglich, scripted devices per API anzulegen? Hast du eine API Beschreibung?

Bei mir läuft der vdcd in Docker. Bisher konnte ich mit Mühe und probieren meine Enocean und Hue devices hinzufügen. Nun möchte ich auch mal probieren scripted devices hinzuzufügen.

Viele Grüße
Marco

luz

mohanisch ist es möglich, scripted devices per API anzulegen?

Ja, die Weboberfläche der P44-DSB macht das ja auch 😉

mohanisch Hast du eine API Beschreibung?

Im Prinzip ist es die vDC-API, in JSON, über einen TCP-Socket (genannt "config API"), mit einigen Ergänzungen. Es gibt eine Beschreibung mit ein paar Beispielen im vdcd-repo hier.
Die ganze vDC-API ist hier in den Dokumenten vDC-API und vDC-API-properties beschrieben.

Um die vDC-API via HTTP zu nutzen, ohne dass man den p44-spezifischen mg44-Server braucht, gibt es den json_api_forwarder in php.

In der API-Beschreibung fehlen allerdings die plan44-spezifischen Ergänzungen. Das sind einige Properties, deren Namen jeweils mit x-p44-beginnt, und ein paar wenige Methoden, ebenfalls mit x-p44- beginnend.

Am einfachsten ist es, auf einer P44-DSB-X mit dem Web-Inspector des Browsers der Web-UI zuzuschauen, wie sie das eine oder Andere macht, und das dann auf der "tweak.html"-Seite auch auszuprobieren.

Im Fall von Erzeugen von scripted devices ist es die vDC-Methode x-p44-addDevice, welche auf dem scripted device vDC mit der JSON-Init-Message als Parameter init aufgerufen werden muss. Das entstehende device hat dann ein Property x-p44-implementation in dem der Script-Text der Implementation gespeichert wird (und ein read-only x-p44-initmessage).

Konkret also etwa so:

/* device anlegen */
{ "method":"x-p44-addDevice", "dSUID": "none", "x-p44-itemSpec":"vdc:Scripted_Device_Container:1", "init":"{ 'message':'init', 'name':'demo light', 'output':'light' }" }
{ "result" : { "dSUID": "xxxxx", "rowid":1, "name":"demo light" }}

/* Script setzen */
{ "method":"setProperty", "dSUID": "xxxxx", "properties":{ "x-p44-implementation":"/* implementation */ return true;" } }
{ "result" : null }

/* implementation neustarten */
{ "method":"x-p44-restartImpl", "dSUID": "xxxxx" }
{ "result" : null }

Viel Erfolg!

mohanisch

Danke Luz! Das funktioniert! Hab mal die Beispiele von dir integriert 🙂

Image description

mohanisch

Hallo @luz,

ich versuche grad ein Gerät per API einzubinden, will aber nicht... Folgende Implementierung will ich absenden:
{ "method": "setProperty", "dSUID": "47FCF5951DCA55878036FCA5BCC77BD200", "properties": { "x-p44-implementation": "var baseurl = \"http://10.11.12.13/api/0857ED05D0/lights/3/state\";on (message()) as m { if (m.message==\"channel\" && m.index==0) { fetch(baseurl,{method: \"PUT\",body: JSON.stringify({\"on\": true})});};return true;" } }

Als Antwort im vdcd erhalten ich:
Aborting 'implementation' because of fatal error: (implementation:1,148): Code literals are not yet supported (ScriptError:16)

Ich hab schon vieles probiert, aber keine Ahnung was ich falsch mache...

luz

Hallo @mohanisch

Wenn ich mal die x-p44-implementation etwas formattiere, dann wäre das:

var baseurl = "http://10.11.12.13/api/0857ED05D0/lights/3/state";

on (message()) as m {
  if (m.message=="channel" && m.index==0) {
    fetch(baseurl, {
      method: "PUT",
      body: JSON.stringify(
        {\"on\": true}
      )}   
    );
  }
} // diese Klammer fehlt in Deinem Code
return true;

Abgesehen von der fehlenden Klammer ist das Problem, dass es fetch nicht gibt in p44script, und auch kein JSON.stringify. p44script ist kein Javascript! Es gibt geturl, posturl und puturl für die einfacheren Fälle, und httprequest, wenn man Detail-Kontrolle über Header, login, etc. braucht. S. Doku.

So wie Deine baseurl aussieht, dürfte das eine hue-API sein, wo Du das Light 3 ein- und ausschalten möchtest?

Das geht mit puturl, etwa:

puturl("http://10.11.12.13/api/0857ED05D0/lights/3/state", '{ "on":true }')

Das kannst Du in einem P44-DSB REPL auch direkt ausprobieren.

Die ganze Implementation Deines device würde dann etwa so aussehen:

var baseurl = "http://10.11.12.13/api/0857ED05D0/lights/3/state";

on (message()) as m {
  if (m.message=="channel" && m.index==0) {
    var msg = format('{ "on": %s }', if (m.value>50, "true", "false"))
    puturl(baseurl, msg)
  }
}
return true;

mohanisch

Danke luz
Hat natürlich funktioniert 🙂

mohanisch

Hallo @luz ,

muss leider wieder ein Problem lösen 🙂
Das Anlegen des Gerätes funktioniert super. Super Doku.. 🙂

Habe da nur ein Problem mit einer "Joker Klemme". Ich lege diese wie folgt an:

{
    "method": "x-p44-addDevice",
    "dSUID": "none",
    "x-p44-itemSpec": "vdc:Scripted_Device_Container:1",
    "init": "{ 'message':'init','name':'Test 1','output':'basic','colorclass':'8', 'dimmable': false, 'buttons': [{'id': 'button1', 'buttonid': 1, 'buttontype': 1, 'element': 0, 'usage': 3, 'group': 8}]} "
}

Soweit so gut, wird in dS angezeigt und ist schaltbar. Nur habe ich ein Problem das value über die SmartHome API vom dSS zu steuern. Die outputId unterscheiden sich zwischen dsDevices und functionBlocks. Ein patch request gibt mir diesen Fehler:

{
    "error": {
        "type": "error",
        "title": "error",
        "status": 500,
        "detail": "Could not find item. deviceOutputId:powerState model/apartment.cpp:1361 patchPath:/functionBlocks/47fcf5951dca55878036fca5bcc77bd200/outputs/powerState/value httpPath:/api/v1/apartment/dsDevices/47fcf5951dca55878036fca5bcc77bd200/status"
    }
}

GET /api/v1/apartment/dsDevices/47fcf5951dca55878036fca5bcc77bd200/status

{
    "data": {
        "id": "47fcf5951dca55878036fca5bcc77bd200",
        "type": "dsDeviceStatus",
        "attributes": {
            "functionBlocks": [
                {
                    "id": "47fcf5951dca55878036fca5bcc77bd200",
                    "outputs": [
                        {
                            "id": "powerState",
                            "value": 0.0,
                            "status": "ok",
                            "targetValue": 0.0
                        }
                    ]
                }
            ],
            "submodules": [
                {
                    "id": "47fcf5951dca55878036fca5bcc77bd200",
                    "operationsLocked": false
                }
            ]
        }
    }
}

GET /api/v1/apartment/functionBlocks/47fcf5951dca55878036fca5bcc77bd200

{
    "data": {
        "id": "47fcf5951dca55878036fca5bcc77bd200",
        "type": "functionBlock",
        "attributes": {
            "name": "Test 1",
            "technicalName": "custom script device",
            "active": true,
            "outputs": [
                {
                    "id": "basic_switch",
                    "attributes": {
                        "technicalName": "switch",
                        "min": 0.0,
                        "max": 100.0,
                        "resolution": 0.10000000000000001,
                        "mode": "switched",
                        "levels": 1.0
                    }
                }
            ],
            "buttonInputs": [
                {
                    "id": "button0",
                    "attributes": {
                        "technicalName": "Pushbutton#0",
                        "type": "appmode",
                        "mode": "button1way"
                    }
                }
            ],
            "submodule": "47fcf5951dca55878036fca5bcc77bd200",
            "deviceAdapter": "47fcf5951dca55878036fca5bcc77bd200"
        }
    }
}

powerStatewäre in dem Fall korrekt, nur geht des net..
https://git.digitalstrom.org/dss/dss-mainline/-/blob/master/src/util.cpp#L175

luz

Da kann ich wenig helfen, das sind dS-Interna, die ich nicht im Detail kenne.

mohanisch powerStatewäre in dem Fall korrekt [...]
https://git.digitalstrom.org/dss/dss-mainline/-/blob/master/src/util.cpp#L175

Eher nicht. Der Output-Channel-Typ powerState ist ein Spezialfall für FCUs (Fan Coil Units = Klimageräte) sowie Audio- und Videodevices, das sind alles Geräte, die neben ein/aus noch standby und ganz aus haben. Eine schwarze Klemme mit "basic" Output hat nix davon, sondern nur einen Standard-Ausgang mit dem Wertebereich 0..100. Das muss ein Mismatch im dSS sein, dass der mit powerState daherkommt.

Vielleicht funktioniert es besser, wenn Du in der init-Message bei output statt basic light nimmst, und zusätzlich group=8 setzt. Die Klemme bleibt so immer noch schwarz, aber der Ausgang ist dann so wie bei einer Lichtklemme, vielleicht gibt das weniger Probleme im dSS.

Im Übrigen: über die vDC-API kannst Du mit

{ "method":"getProperty", "dSUID":"xxxx", "query":{ "output*":null, "channel*":null } }

alle ausgangsrelevanten Infos eines Gerätes (Properties beginnend mit output oder channel) abfragen, und so Unterschiede von eigenen Devices zu anderen untersuchen.
Oder gleich alle Properties eines Devices (das ist dann aber ein grosses Resultat!):

{ "method":"getProperty", "dSUID":"5FE395EDD692581A807BD42C0A77615500", "query":null }