You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+36-122
Original file line number
Diff line number
Diff line change
@@ -15,141 +15,55 @@ A HomeMatic CCU Addon implementing a xml request functionality as an interface t
15
15
## Installation
16
16
This addon can be added like a usual CCU addon package via the WebUI provided functionality by selecting "System-Konfiguration » Systemsteuerung » Zusatzsoftware", to upload the addon package as a tar.gz and the use »Installieren« to actually install the addon. After a restart of the CCU the xml-api interface can then be selected from the »Zusatzsoftware« tab in the CCU settings.
17
17
18
-
## Security advice
19
-
The call to one of the API routines is without any authentication. If the HomeMatic control center can be reached via the Internet without special protection, **this is a serious security risk!**
20
-
21
18
## Use
22
19
After installation the XML-API should be avilable via the following URL call:
where [CCU_IP] corresponds to the IP address or name of your CCU device and [ScriptName] being one of the following tool scripts:
23
+
where [TOKEN_ID] corresponds to a stateless token-based authentication id a user can register using the `tokenregister.cgi` script listed below. In addition, [CCU_IP] corresponds to the IP address or hostname of your CCU device and [ScriptName] being one of the following scripts:
| `devicelist.cgi` | Lists all devices with their channels. Contains name, serial number, device types and ids.<br> `show_internal=1` (outputs all internal channels also)
31
-
| `functionlist.cgi` | Lists all functions with their channels.
32
-
| `favoritelist.cgi` | Lists all favorites and users.<br>`show_datapoint` (outputs also attribute `datapoint_id` and `datapoint_type`)
33
-
| `mastervalue.cgi` | Returns one or more (1234,5678) devices with their names and values of their master values.<br>`device_id=1234` (returns all master values of device)<br>`requested_name=TEMPERATURE_COMFORT,TEMPERATURE_LOWERING` (returns only master values for specified names)
34
-
| `mastervaluechange.cgi` | Sets one or more (TEMPERATURE_LOWERING,TEMPERATURE_COMFORT) master values of one or more (1234,5678) devices.<br>`device_id=1234` (sets master values of device)<br>`name=TEMPERATURE_LOWERING` (sets specified master value only)<br>`value=17.0,22.5` (sets master values to specified values)
27
+
| `checkuptodate.cgi` | ???
28
+
| `devicelist.cgi` | Lists all devices with channels. Contain names, serial number, device type and ids.<br> `show_internal=0/1` - adds internal channels also (default=0)
29
+
| `devicetypelist.cgi` | Lists all possible device types with their possible meta data.
30
+
| `exec.cgi` | Allows to execute arbitrary ReGaHss script commands (as POST data).
31
+
| `favoritelist.cgi` | Lists all favorites and users.<br>`show_datapoint=0/1` - outputs datapoint_id and datapoint_type also (default=0)<br>`show_internal=0/1` - adds internal channels also (default=0)
32
+
| `functionlist.cgi` | Lists all functions including channels.
33
+
| `mastervalue.cgi` | Outputs a single or several '1234,5678' devices with their names and master values.<br>`device_id=list` - returns master values of specified devices (e.g. "1234,5678")<br>`requested_names=list` - returns only master values of selected types (e.g. "TEMPERATURE_COMFORT,TEMPERATURE_LOWERING")
34
+
| `mastervaluechange.cgi` | Sets one or more master values for a list of devices.<br>`device_id=list` - sets master values of specified devices (e.g. "1234,5678")<br>`name=list` - sets only master values of selected types (e.g. "TEMPERATURE_LOWERING,TEMPERATURE_COMFORT")<br>`value=list` - sets master values to specified values (e.g. "17.0,22.5")
35
+
| `programactions.cgi` | Allows to change active and visible program options.<br>`program_id=int` - id of program to modify (e.g. "1234")<br>`active=true/false` - sets active status of program to true/false<br>`visible=true/false` - sets visible status of program to true/false
35
36
| `programlist.cgi` | Lists all programs.
36
-
| `programactions.cgi` |change the Programactions active and visible <br><b>Parameter</b>: programactions.cgi?program_id=1234&active=true&visible=true
37
-
| `protocol.cgi` | Returns the system protocol.<br>`clear=1` (clears the system protocol)
38
-
| `runprogram.cgi` | Starts the specified program.<br>`program_id=1234` (id of program to start)
39
-
| `roomlist.cgi` | Lists all rooms with their channels.
40
-
| `rssilist.cgi` | Lists all devices with their signal strength.
41
-
| `scripterrors.cgi` | Searches the last 10 lines of `/var/log/messages` for homematic-script errors and output these.
42
-
| `state.cgi` | Returns for single or multiple devices (1234,5678) the channels and their values.<br>`device_id=1234` (id of the device to return values)<br>`channel_id=5678` (id of the channel to return values)<br>`datapoint_id=12839` (id of data to return only Value())
43
-
| `statelist.cgi` | Lists all devices with channels and current values.<br>`ise_id` (id of devices to list values for)<br>`show_internal=1` (also return internal attribute state)
44
-
| `statechange.cgi` | Changes one or more channel states.<br>`ise_id=1234,5678` (id of the channels)<br>`new_value=0.20` (new value for channel state)
45
-
| `systemNotification.cgi` | Returns the current system notifications
46
-
| `systemNotificationClear.cgi` | Clears all current clearable system notifications.
47
-
| `sysvarlist.cgi` | Lists all system variable with values.<br>`text=true` (return current value of system variable in attribute value_text)
48
-
| `sysvar.cgi` | Returns single system variable with values.<br>`ise_id=1234` (id of system variable)
49
-
| `version.cgi` | Outputs version of XML-API
50
-
51
-
All of these scripts, if called, generate a xml structured output that can then be used by third-party applications to display or modify certain information.
52
-
All of these scripts rely on a `ise_id` device or channel identifier. You can get this `ise_id` for the needed datapoint by analysing the result of `statelist.cgi`. The id can be used in the following way:
37
+
| `protocol.cgi` | Outputs the system protocol.<br>`start=int` - start of the protocol<br>`show=int` - number of entries to output<br>`clear=0/1` - allows to clear the system protocol
38
+
| `roomlist.cgi` | Lists all configured rooms including channels.
39
+
| `rssilist.cgi` | Lists RSSI values of all RF devices.
40
+
| `runprogram.cgi` | Starts a program with the specified id.<br>`program_id=int` - id of program to modify (e.g. "1234")
41
+
| `scripterrors.cgi` | Searches for the last 10 lines in `/var/log/messages` containing script runtime errors and outputs them.
42
+
| `state.cgi` | Outputs one or more devices with their channels and current values.<br>`device_id=list` - returns values of specified devices (e.g. "1234,5678")<br>`channel_id=list` - returns values of specified channels (e.g. "1234,5678")<br>`datapoint_id=list` - returns Value() for datapoint with id (e.g. "1234,5678")
43
+
| `statechange.cgi` | Allows to change the state of one or more devices.<br>`ise_id=list` - selects the devices with the specified ids (e.g. "1234,5678")<br>`new_value=list` - new values for device states (e.g. "0.20,1.45")
44
+
| `statelist.cgi` | Outputs all devices with channels and their current values.<br>`ise_id=int` - output only channels and values of device with specified id (e.g. "1234")<br>`show_internal=0/1` - adds internal channels also (default=0)
45
+
| `systemNotification.cgi` | Outputs the currently existing system notifications.
46
+
| `systemNotificationClear.cgi` | Clears the current active system notifications (if not sticky).
47
+
| `sysvar.cgi` | Outputs a single system variable with its corresponding values.<br>`ise_id=int` - the id of the system variable to output (e.g. "1234")<br>`text=true/false` - outputs or suppressed the text for string variables (default=true)
48
+
| `sysvarlist.cgi` | Outputs all system variables with their corresponding values.<br>`text=true/false` - outputs or suppressed the text for string variables (default=false)
49
+
| `tokenlist.cgi` | Lists all registered security access tokens.
50
+
| `tokenregister.cgi` | Registers a new security access token.<br>`desc=string` - description for new token id
51
+
| `tokenrevoke.cgi` | Revokes an existing security access token.<br>`sid=string` - security access token id
All of these scripts, in addition to the listed parameters require a security access token id to be specified via a mandatory `?sid=[TOKEN_ID]` URL parameter with an adequate token ID specified. Such a security token can be generated using `tokenregister.cgi` from within the standard CCU addon webui page (`Settings -> Control panel -> Additional software -> XML-API -> Set`) or by using an already registered security token. Furthermore, already registered tokens can be listed via `tokenlist.cgi` and revoked via `tokenrevoke.cgi` with the token id supplied.
56
+
57
+
If a script will be correctly called, it generates a xml structured output that can then be used by third-party applications to display or modify certain information.
58
+
59
+
In addition many of these scripts rely on additional URL parameter to be specifeid (e.g. `ise_id` device or channel identifier). And example of such script executing URL can be seen here:
* state.cgi - Abfrage Abfrage von mehreren IDs hinzugefügt (z.Bsp.: state.cgi?device_id=12796,1245789 )
108
-
* neues cgi systemNotification.cgi - Gibt die System Meldungen aus
109
-
* neues cgi systemNotificationClear.cgi - Löcht die vorhandenen System Meldungen
110
-
111
-
1.5
112
-
* Bugfix
113
-
* Anpassung für CCU2
114
-
115
-
1.4
116
-
* Datenpunktausgabe "value_name_0 und value_name_1" in sysvar.cgi und sysvarlist.cgi hinzugefügt
117
-
118
-
1.3
119
-
* Datenpunktausgabe "unit" in state.cgi und statelist.cgi hinzugefügt
120
-
* scripterrors.cgi - Sucht in den letzten 10 Zeilen von /var/log/messages nach Homematic-Script Fehlermeldungen
121
-
122
-
1.2-hq10
123
-
* Ausgabe von version.cgi von 1.3 auf 1.2 zurück-geändert um Probleme mit Homedroid zu vermeiden
124
-
* statechange.cgi - Anführungszeichen hinzugefügt damit auch Varialben vom Typ Zeichenkette gesetzt werden können
125
-
126
-
1.2-hq9
127
-
* neues cgi scripterrors.cgi hinzugefügt. Gibt aus den letzten 10 Zeilen der /var/log/messages Homematic-Script Fehlermeldungen aus
128
-
129
-
1.2-hq8
130
-
* Fehler in sysvarlist.cgi behoben, 3 Attribute haben gefehlt. (Danke Monty)
131
-
132
-
1.2-hq7
133
-
* Datenpunktausgabe in favoritelist.cgi arbeitet nun wie erwartet (gleiches verhalten wie state.cgi, danke Monty).
134
-
135
-
1.2-hq6
136
-
* exec.cgi (von http://homematic-forum.de/forum/viewtopic.php?f=31&t=7014) hinzugefügt. Liefert zwar json und kein xml - passt aber thematisch imho trotzdem dazu
137
-
* favoritelist.cgi - Parameter show_datapoint aktiviert Ausgabe der zugehörigen Datenpunkte bzw systemvariablen (übernommen aus statelist.cgi und sysvar.cgi). Paramter show_internal siehe statelist.cgi
138
-
* statelist.cgi - Parameter show_internal=1 aktiviert nun die Ausgabe des Datenpunkt-Attributs state
139
-
* info.html aktualisiert
140
-
141
-
1.2-hq5
142
-
* version.cgi liefert nun 1.3 zurück
143
-
* protocol.cgi hinzugefügt: Gibt das Systemprotokol zurück. Parameter: start, show, clear. clear=1 löscht das Protokoll
144
-
145
-
1.2-hq4
146
-
* allow-origin Header hinzugefügt
147
-
* info.html aktualisiert
148
-
149
-
1.2-hq3
150
-
* sysvar.cgi hinzugefügt: Gibt eine einzelne Variable zurück. Liefert Wertelisten. Parameter: ise_id
151
-
* sysvarlist.cgi: neuer Parameter text um die neuen Attribute value_list and value_text zu aktivieren (text=true)
152
-
* cgi.tcl und once.tcl entfernt
153
-
154
68
## Authors
155
69
* jens-maus, Maik (Monty1979), Philipp (ultrah), hobbyquaker, dirch, Uwe (uwe111)
0 commit comments