HomeMatic

Homematic offers for nearly every situation of living in a house a good solution: The home control system makes live easier and controls repeating actions in the house, like for example the opening of blinds or the garage door.

You will find more details under the following links:

What you'll not find there or probably anywhere else, is a modul for an AMX controller to control your HomeMatic components. The controllers from AMX are freely programable and have several different interfaces. This makes this controllers perfect for controlling your home, an office or anything else.

Integrating the module

If you don't know AMX than stop reading here. This documentation will be useless for you. If this is what you want to know, than read on

To make use of this module you need a CCU2 from HomeMatic or something compatible. You should know the serial numbers of the homematic components and have installed the XMLAPI addon. Then you will also need the ISE-IDs of all components.
If you have all this done, we can go on integrating the module.

First you should download. the module. Inside the ZIP file are 2 files:

Inside the include file are only some type definations you'll need for your own UI module.

The following code shows how to integrate the module:

DEFINE_DEVICE
   dvClient = 0:4:0;
   dvServer1 = 0:5:0;
   dvServer2 = 0:6:0;
   dvServer3 = 0:7:0;

   vdvHomeMatic = 33000:1:0;

DEFINE_VARIABLE
   volatile dev dvHomeMatic[] = { dvServer1, dvServer2, dvServer3, dvServer4, dvServer5 };

   volatile integer nPort = 2001;    // This is for RF components
// volatile integer nPort = 2000;    // This is for IP components
   volatile char sIP[] = '10.10.10.10';  // IP of your CCU2

DEFINE_MODULE 'HomeMaticRPC_Comm' HM_Comm(vdvHomeMatic, dvClient, dvHomeMatic, sIP, nPort);

The defination of three devices (you can define up to 10) allows up to 3 concurrent connections to the controller on the same port. The module uses RPC (remote procedure call) to get respnses from the CCU2. This changes the client / server logic and the AMX controller becames a server. Because RPC communicates similar to HTTP, the connection is disconnected after every call. Therefore the server have to be started new. To avoid time gaps, always 2 servers are running and listening on the same port.

The AMX module first creates the server listening. After this it sends a command to the CCU2 and subscribes to it. This makes the CCU2 reporting all events immediately. The AMX module reads the informations and makes small easy readable responses out of it. You can take this informations to build an UI (user interface) module to visualize the information. It's up to you how you do that in detail.

Command to the module

All commands consist of the command itself and one or more parameters. The parameters are separated from the command and from themself by a colon. Every command is terminated by a semicolon. This allows more than one command per line. But a line should not be longer than 255 charachters!

Example:
    SET VALUE:OEQ1234567.1:1:1;

Command Parameter Descrition
STATECHANGE <ISE ID><Type><Wert> Dieser Befehl sendet einen neuen Status an einen beliebigen Aktor. Die Parameter haben folgende Bedeutung:
  • <ISE ID>  Die ISE_ID der Komponente.
  • <Type>   Die Type des Parameters. Siehe dazu TYPEN weiter hinten.
  • <Wert>   Der zu sendende Wert. Dieser muss dem Parameter Type entsprechen!
Der folgende Befehl setzt einen Dimaktor auf 65%:
STATECHANGE:1234:2:0.65;
STATE <ISE ID> Dieser Befehl fragt die über den Parameter angegebene Komponente ab.
Der Parameter <ISE ID> muss eine gültige ISE_ID enthalten. Als Antwort
wird der Status, Level und weitere Informationen der Komponente geliefert.
DEBUG <Wert> Dieser Befehl schaltet das Debugging ein oder aus. Wird als Parameter 1 übergeben,
wird das Debugging aktiviert. Es werden verschiedenste Informationen in Form von Befehlen
zurückgemeldet. Wird als Parameter 0 übergeben, wird das Debugging deaktiviert.
Alle Rückmeldungen kommen über das virtuelle Device und beginnen immer mit
SET VALUE
<ADDR><Type><Wert>
Dieser Befehl sendet einen neuen Status oder einen Wert an eine Komponente.
Dieser Befehl wird als XML-RPC abgesetzt. Als Antwort kommt der neue Status der Komponente
zurück. Die Parameter haben folgende Bedeutung:
  • <ADDR>  Die Seriennummer der Komponente.
  • <Type>   Die Type des Parameters. Siehe dazu TYPEN weiter hinten.
  • <Wert>   Der zu sendende Wert. Dieser muss dem Parameter Type entsprechen!
Der folgende Befehl schaltet einen einfachen Schaltaktor ein:
SET VALUE:OEQ12345678.1:1:1;
GET VALUE
<ADDR><Type>
Dieser Befehl fragt die über den Parameter <ADDR> angegebene Komponente ab.
Der Parameter <ADDR> muss eine gültige Seriennummer enthalten. Der Parameter
<Type> muss dem erwarteten Typ des Werts entsprechen. Als Antwort wird der Status, Level oder ein
anderer Wert der Komponente geliefert.

Die in der Tabelle mit rot geschriebenen Befehle, sind zwar implementiert, funktionieren aber nicht. Offenbar sind diese Befehle nicht in der CCU2 implementiert oder die XML-Struktur muss anders aufgebaut werden. Für Hinweise bin ich dankbar.

Rückmeldungen des Moduls

In der folgenden Tabelle sind die (bisher) möglichen Rückmeldungen des Moduls dokumentiert.

Befehl Parameter Beschreibung
EVENT <ADDR>:<Type>:<Wert> Das ist die Antwort auf den Befehl STATECHANGE oder einem Ereignis wie die
Statusänderung eines Schaltaktors, Dimaktors, …
Ist der Parameter <ADDR> leer, dann handelt es sich um ein Ereignis auf Grund eines vom
Modul abgesendeten Befehls. Das muss nicht zwangsweise ein vom UI-Modul ausgelöster Befehl sein,
sondern kann auch von einem im Modul automatisch ausgelösten Befehl stammen.
Die Parameter haben folgende Bedeutung:
  • <ADDR>   Die Seriennummer der Komponente auf die sich die Antwort bezieht.
  • <Type>   Die Type des folgenden Parameters.
  • <Wert>   Der zurückgemeldete Wert.
Beispiel:
EVENT:OED1234567.1:2:0.65;
RESULT <ISE ID>:<Wert> Diese Antwort erfolgt immer auf den Befehl STATECHANGE und enthält den aktuellen
Wert oder Status der zuletzt geschalteten Komponente. Die Parameter haben folgende Bedeutung:
  • <ISE ID>   Die ISE-ID der Komponente auf die sich die Antwort bezieht.
  • <Wert>   Der aktuelle Wert der entsprechenden Komponente.
Bespiel:
RESULT:1234:0;
WORKING <ADDR>:<Type>:<Wert> Zeigt an ob eine Komponente gerade beschäftigt ist, oder nicht.
  • <ADDR>   Die Seriennummer der Komponente auf die sich die Antwort bezieht.
  • <Type>   Die Type des folgenden Parameters (immer 1).
  • <Wert>   Der zurückgemeldete Wert.
Beispiel:
WORKING:OED12345678.1:1:0;
PRESS <Wie>:<ADDR>:<Wert> Wird ein Wandtaster gedrückt, dann wird diese Rückmeldung gesendet. Das Ergebnis
ist immer ein boolscher Wert. Die Parameter haben folgende Bedeutung:
  • <Wie>   Dieser Parameter kann “SHORT”, für einen kurzen
    Tastendruck, oder “LONG” für einen langen Tastendruck sein.
  • <ADDR>   Die Seriennummer der Komponente auf die sich die Antwort bezieht.
  • <Wert>   1 = Taste gedrückt, 0 = Taste losgelassen.
Beispiel:
PRESS:SHORT:OED12345678.1:1;
LEVEL <ADDR>:<Wert> Diese Rückmeldung kann von einem Dimaktor, einem Thermometer oder einer anderen
Komponente stammen, die einen Fließkommawert zurückmeldet. Der Inhalt des Parameters
<Wert> ist in jedem Fall eine Fließkommazahl. Bei Dimaktoren ist das ein Bereich von
0.00 bis 1.00.
  • <ADDR>   Die Seriennummer der Komponente auf die sich die Antwort bezieht.
  • <Wert>   Fließkommawert.
Beispiel:
LEVEL:NEQ12345678.2:0.65;
DIRECTION <ADDR>:<Wert> Datentyp Integer. Gibt die Richtung (Senden oder Empfangen) dieses Kanals in einer
direkten Verknüpfung an.
Die Parameter haben folgende Bedeutung:
  • <ADDR>   Die Seriennummer der Komponente auf die sich die Antwort bezieht.
  • <Wert>   Kann folgende Werte beinhalten:
    • 0 = DIRECTION_NONE (Kanal unterstützt keine direkte Verknüpfung)
    • 1 = DIRECTION_SENDER
    • 2 = DIRECTION_RECEIVER
Beispiel:
DIRECTION:OEQ12345678.1:1;
ERROR <Fehler>:<ADDR>:<Wert> Meldet einen Fehlerzustand. Der <Wert> ist immer boolean und zeigt ob
ein Fehler vorliegt. Die Parameter haben folgende Bedeutung:
  • <Fehler>   Kann folgende Werte annehmen.
    • OVERLOAD bedeutet bei einem Dimaktor, dass der angeschlossene Verbraucher zu viel
      Strom verbraucht.
    • OVERHEAT bedeutet, dass die Komponente überhitzt ist.
    • UNREACH Komponente war nicht erreichbar.
    • STICKY_UNREACH Komponente war irgendwann nicht erreichbar.
  • <ADDR>   Die Seriennummer der Komponente auf die sich die Antwort bezieht.
  • <Wert>   1 = Fehler liegt vor, 0 = Kein Fehler.
PONG <ID> Diese Rückmeldung ist die Antwort auf ein intern abgesetztes PING. Dieser
Befehl wird immer dann abgesetzt, wenn mindestens 10 Sekunden lang kein Befehl abgesetzt wurde.
Als Parameter wird immer “20170622” übergeben.

Datentypen

Zur besseren Lesbarkeit der einzelnen Datentypen gibt es in der Datei HomeMaticRPC.axi einige der wichtigsten Datentypen vordefiniert. Die Datei kann mit folgendem Befehl in ein eigenes Modul eingebunden werden:

#include 'HomeMaticRPC'

Die folgende Tabelle erkärt die einzelnen Datentypen:

Wert Name Beschreibung
0 RPC_TYPE_NONE Kein oder unbestimmter Inhalt
1 RPC_TYPE_BOOL Ein boolscher Wert. Kann 0 oder 1 sein. Wahlweise auch “false” oder “true”.
2 RPC_TYPE_INT Ein ganzzahliger Wert.
3 RPC_TYPE_FLOAT Ein Fließkommawert.
4 RPC_TYPE_STRING Eine beliebige Zeichenkette.
5 RPC_TYPE_TIMESTAMP Datum und Uhrzeit (Zeitstempel). Dieser Datentype ist derzeit nicht unterstützt!

© 2006 − 2011 by Andreas Theofilu (theosys)