[dss-developer] WG: Question about dss Web

Wed Aug 25 16:15:33 CEST 2010

Hi Dev-List, Hi Xue

The dSK20 has a prototype dSS with a minimal software (no scripting and no long-term-metering-storage), but it has a webinterface, which differes in the json calls from the opensource dss, but can provide the same features (attempts to provide the same interface from the older dSS in the newer dSS were not successful) ….

So you can write a App for digitalSTROM and you can use the dSK20 Interface, but you should be aware that without a addition plugin the official opensource dSS will have a other interface. But I’m sure, that you can handle it ☺.
It is true, that there is no documentation about the JSON-Calls for that dSK dSS, according to the original timeframe the opensource dSS should has already been world standard, so I was too lazy to make such a documentation ☺.
But there is a js-file in the Webinterface which covers most oft he possible json calls, you can make tot he dSK, it is the digitalSTROM.js (http:serverid/digitalstrom.js), where all json-calls are encapsulated as a javascript command with the http-requests. There you can look at to see what command you can use.

Additional I can provide you these guildlines which I have provided some partners (sorry, only german):

Struktur dSS in dSKXX (dSS10)

Das Wohnungs API besteht aus den Definition für Objekte und Zugriffs Methoden. Das digitalSTROM
System wird mit fünf Objekt Klassen abgebildet:

·         Apartment: Ein einzelnes Objekt für jede dS Installation

·         Group: digitalSTROM Farb- und Benutzergruppen

·         Zone: Festlegung von Räumen

·         Circuit: Entspricht einem Schaltkreis

·         Device: Ein digitalSTROM Gerät, Schalter oder Sensor

·
Für jedes Objekt besteht eine Reihe von Methoden zur Identifikation, Abfrage von Information und
Steuerung.

Die Objekt Klasse Device steht für ein digitalSTROM Device, also alle dSID Chips und dS-ready
Geräte. Ein Device ist beschrieben durch seine eindeutige dSID und Funktions-ID, und kann mit
einem Namen gekennzeichnet werden. Jedes Device kann mehreren Gruppen angehören, ist aber
mindestens Mitglied einer vordefinierten digitalSTROM Farbgruppe. Jedes Device kann genau einer
Zone zugeordnet werden. Definitionsgemäß kann es natürlich auch nur genau in einem Circuit
vorhanden sein.

Die Objekt Klasse Circuit entspricht einem physikalischen Stromkreis und beschreibt somit genau
einen digitalSTROM Meter. Ein Circuit wird beschrieben durch die dSID des zugehörigen Meters und
kann mit einem Namen gekennzeichnet werden. Ein Circuit kann in mehreren Zonen vorhanden
sein und damit in virtuelle Schaltkreise aufgeteilt werden.

Die Objekt Klasse Zone beschreibt die realen Räume oder räumlichen Abgrenzungen im Gebäude.
Eine Zone kann sich über mehrere Schaltkreise erstrecken und dementsprechend mehrere Devices
aus unterschiedlichen Schaltkreisen beinhalten.

Die Objekt Klasse Group kann von drei Typen abstammen: den vordefinierten digitalSTROM
Farbgruppen, einer benutzerdefinierten Gruppe in einer Zone und einer benutzerdefinierten Gruppe
die sich über die gesamte Installation erstreckt. Auch eine Benutzergruppe kann mit einem Namen
gekennzeichnet werden.

Die Objekt Klasse Apartment beinhaltet alle Circuits und Zonen der Installation, und die in ihnen
enthaltenen Devices und Gruppen.

Die Befehle zur Steuerung sind für ein Device und eine Gruppe in gleicher Art vorhanden. Für beide
Objekte lassen sich die Ausgangswerte erhöhen, vermindern, das Maximum, Minimum oder eine
definierte Szene einstellen.

…

JSON

JavaScript Object Notation (JSON) ist ein textbasiertes Datenaustauschformat, es basiert auf einer
Untermenge der JavaScript Programmiersprache, Standard ECMA-262. Die Verwendung ist
allerdings nicht nur auf JavaScript Umgebungen beschränkt, für alle geläufigen
Programmiersprachen existieren Parser und Interfaces zu JSON.

Der Aufruf einer Methode des Wohnungs API erfolgt mittels HTTP und der folgenden Notation:
HTTP/Get http://a.b.c.d/api/basic?
class=n
& function=m
& selector=a0b1c2d3
& subselector=a4b5c6d7
& parameter=anytext

Die Werte n und m für class und function werden numerisch angegeben und sind im Wohnungs API
für jede Methode definiert. Selector und subselector sind hexadizimal dargestellte Qualifizierer des
Methoden Aufrufs, in der Regel die textuelle Darstellung der dSID eines Objektes. Optional ist ein
weiterer parameter möglich, ebenfalls in Textform.

Best Practice

http://url/api/basic?class=0&function=0 : Liefert die Struktur der digitalSTROM Installation als JSON-String. Es kann mit einen Befehl sofort alle Circuits (dSM) mit angeschlossenen Devices bzw. alle logischen Zones (Räume) mit Ihren Gruppen zurückgegeben werden.
http://url/api/basic?class=0&function=1 : Liefert eine Struktur mit allen dSMs mit ihren aktuellen Energiemesswert zurück.

Wir empfehlen Dringend die Steuerung über Gruppen, genauer Gruppen der Zonen.
Zwar geht auch die direkte Steuerung von  Devices, es entspricht aber nicht den digitalSTROM Konzept, da per Taster eben auch nur Gruppenbefehle schicken wird.

Man benötigt hierbei die ZoneID, die über Apartment-Classe abfragbar ist, z.B. mit dem Iterator getZoneByIndex. Die ZoneID ist relativ willkürlich gewählt, muss daher abgefragt werden. Man kann diese Nummer aber auch der gesamten Datenstruktur entnehmen.
http://url/api/basic?class=1&function=9&parameter=0 (ruft die ID des ersten Raumes ab)

Für den Aufruf einer Szene benötigt man noch eine Gruppennummer, die ebenfalls über einen Iterator kommen kann, aber hier gilt immer für die ersten 10 Gruppen Standardwerte, daher wird immer Gruppe 1 alle gelben Klemmen und damit die Lichtgruppe ansprechen. Da kann man bei normen Gruppen Konstanten nehmen.

Idealerweise wird für die Ansteuerung der selectScene Befehle der Group Klasse verwendet.
http://url/api/basic?class=3&function=16&selector=GroupNr&subselector=ZoneNr&parameter=Szenennummer

Folgende Szenen sind die „richtigen“ für die normale Steuerung:
 0: Ausszene
 5: Anszene
17: Szene 2
18: Szene 3
19: Szene 4
48: Standby: Ausszene mit Löschung der lokalen Priorisierung
49: DeepOff: Ausszene für alle Geräte
11: Wert verringern (Dimmen)
12: Wert verringern (Dimmen)
13: Minimalwert (sprich AUS)
14: Maximalwert (sprich AN)

Die anderen Szenen dienen teilweise speziellen Zwecken, die 6 gelisteten sind die am meisten verwendeten und werden auch von Lichtschaltern gesteuert.
Neben den Szenen kann im Augenblick zum Ausschalten auch ein StartDimDec bzw. ein StopDim ausgeführt werden, ein Anschalten durch ein StartDimInc, ich bitte aber darum, dies nach Möglichkeit zur vermeiden, da diese Befehle nicht wirklich für die Lichtsteuerung geeignet sind. Insbesondere sind dann Steuerbefehle aus einen Webfrontend nicht mehr synchron mit der Bedienung am Taster. Wenn man konsequent auf dem Frontent die oben beschrieben Szenen zum schalten verwendet, so bewahrt man die Synchronität.

Synchronität in Bezug zum Bedienkonzept: Einfaches Beispiel: ein Druck auf den Taster schaltet das Licht an, ein weiterer Druck (etwas später) schaltet das Licht wieder aus. Wenn vom Webfrontend ein selectScene mit 5 an einen ausgeschalteten Raum kommt, wird dieser angeschaltet, und der nächste Wandtasterdruck schaltet den Raum wieder ab. Wenn aber nun ein startDimInc ausgeführt werden würde, kann es sein, dass das Licht im Raum selbst leuchtet, aber der Raum noch der Meinung ist, er sei abgeschaltet, ein Druck auf den Taster würde nun anstatt das Licht auszuschalten die Szene 5 aufrufen.
Hierbei gilt aber bei Deviceansteuerung dies nicht. Ein Device kann in einen beliebigen Modus gefahren werden, ein Tasterdruck erzeugt einen Gruppenbefehl, dieser übersteuert das Device, sofern es nicht wirklich lokal bedient worden ist.

Devices und Circuit werden anders selektiert. Die selector und subselector Werte sind hierbei die dSID als String. Diesen muss man dann bei den apicalls auch wieder zurückreichen. Ansonsten funktioniert der Zugriff ähnlich d.h. es können ebenfalls die gleichen Szenen aufgerufen wrden.

Ich empfehle, nicht eigene Gruppen zu bilden, denn dies ist noch nicht komplett durchgetestet.  Ich empfehle, keine verwaltenden Funktionen wie AddRoom,registerDeviceInRoom usw. zu verwenden, die direkt Einfluss auf die Struktur der Installation nehmen. Zwar funktionieren diese Befehle, aber es kann dort durch Fehlbedienung schnell Chaos entstehen und seltsame Effekte auftreten.

Von: Xue Chen [mailto:xuechen628 at googlemail.com]
Gesendet: Mittwoch, 25. August 2010 15:48
An: Hofmann, Christoph
Betreff: Re: [dss-developer] Question about dss Web

Hi Hofmann,
Thanks for your Help!! I am a student in FH Hagenberg, in our FH we have only  "Aizo Demokoffer dSK20", I want use it development a iPhone App(control the devices in iPhone through dSS, e.g. turn on or turn off the light). so, now I can't use your open source dSS software, can you give me some suggestions, where can I get the dSS software for dSK20? How can I do for my project?

Thanks for your help!!!
Xue Chen
xuechen628 at googlemail.com<mailto:xuechen628 at googlemail.com>

在 25.08.2010，15:02， Hofmann, Christoph 写道：

Hi Xue,

our open source dSS software is a software which can run on linux, windows (using cygwin) or ARM platforms and so on. This software is written in c++ and can be compiled using our makefiles. The files from the „core“ folder and the files from all other folders are needed to build this software. As this dSS software also contains a webserver, the webroot folder contains web-files for that.

Your dSK20 has a very old dSS module which uses a completely different platform which CAN NOT RUN OUR OPEN SOURCE DSS SOFTWARE!!!

As our new dSS module (dSS11) is not available for the public right now you can use our open source software on any PC or MAC. You can use a common RS485->USB module to connect our dS485 bus from the dSM modules to your PC. Please refer to the dSK20 documentation and our documentation in Redmine.

Best regards
Christoph

Von: dss-developer-bounces at forum.digitalstrom.org<mailto:dss-developer-bounces at forum.digitalstrom.org> [mailto:dss-developer-bounces at forum.digitalstrom.org] Im Auftrag von Xue Chen
Gesendet: Mittwoch, 25. August 2010 14:12
An: dss-developer at forum.digitalstrom.org<mailto:dss-developer at forum.digitalstrom.org>
Betreff: [dss-developer] Question about dss Web

Dear digitalSTROM team,
I still have a question about dss websrc.

1. I used Aizo Demokoffer dSK20 and connect through the network cable between the dSS and computer, when I browse to "http://localhost:8080/browse/", it has been running just display "loading..."
and in "http://localhost:8080/browse/setup.html" have nothing too.. Did I something wrong? (I used tomcat and copy the files from "/dss-mainline/data/webroot" to "/apache-tomcat/webapps/browse/", how should I do?)

2. What is the role of these c++ code in the directory(e.g. in "core")?

Thank you very much for your help!!
Have a nice day!

P.S. Patrick, Thanks your Help and hope you have a nice holiday!!

Xue Chen
xuechen628 at googlemail.com<mailto:xuechen628 at googlemail.com>

_______________________________________________
dss-developer mailing list
dss-developer at forum.digitalstrom.org<mailto:dss-developer at forum.digitalstrom.org>
http://forum.digitalstrom.org/cgi-bin/mailman/listinfo/dss-developer

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://forum.digitalstrom.org/pipermail/dss-developer/attachments/20100825/683a61fa/attachment.htm>