Skip to content

Maik2208/XML-API

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

XML-API CCU Addon

Release Downloads Issues License

A HomeMatic CCU Addon implementing a xml request functionality as an interface to all homematic deviced available to a CCU device. This addon provides useful scripts that can be accessed via a HTTP request to a CCU device and allows to query and set all e.g. room- and devicetype names.

Supported CCU models

Installation

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.

Use

After installation the XML-API should be avilable via the following URL call:

https://[CCU_IP]/addons/xmlapi/[ScriptName]?sid=[TOKEN_ID]

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:

ScriptName Description / Parameters
checkuptodate.cgi ???
devicelist.cgi             Lists all devices with channels. Contain names, serial number, device type and ids.
device_id=list - returns values of specified devices (e.g. "1234,5678") (optional)
show_internal=0/1 - adds internal channels also (default=0)
show_remote=0/1 - adds output of virtual remote channels (default=0)
devicetypelist.cgi Lists all possible device types with their possible meta data.
exec.cgi Allows to execute arbitrary ReGaHss script commands (as POST data).
favoritelist.cgi           Lists all favorites and users.
show_datapoint=0/1 - outputs datapoint_id and datapoint_type also (default=0)
show_internal=0/1 - adds internal channels also (default=0)
functionlist.cgi           Lists all functions including channels.
mastervalue.cgi             Outputs a single or several '1234,5678' devices with their names and master values.
device_id=list - returns master values of specified devices (e.g. "1234,5678")
requested_names=list - returns only master values of selected types (e.g. "TEMPERATURE_COMFORT,TEMPERATURE_LOWERING")
mastervaluechange.cgi       Sets one or more master values for a list of devices.
device_id=list - sets master values of specified devices (e.g. "1234,5678")
name=list - sets only master values of selected types (e.g. "TEMPERATURE_LOWERING,TEMPERATURE_COMFORT")
value=list - sets master values to specified values (e.g. "17.0,22.5")
programactions.cgi Allows to change active and visible program options.
program_id=int - id of program to modify (e.g. "1234")
active=true/false - sets active status of program to true/false
visible=true/false - sets visible status of program to true/false
programlist.cgi             Lists all programs.
protocol.cgi               Outputs the system protocol.
start=int - start of the protocol
show=int - number of entries to output
clear=0/1 - allows to clear the system protocol
roomlist.cgi               Lists all configured rooms including channels.
rssilist.cgi Lists RSSI values of all RF devices.
runprogram.cgi             Starts a program with the specified id.
program_id=int - id of program to modify (e.g. "1234")
cond_check=0/1 - execute program with normal condition checks or not (only first "then" is executed) (default=0)
scripterrors.cgi           Searches for the last 10 lines in /var/log/messages containing script runtime errors and outputs them.
state.cgi                   Outputs one or more devices with their channels and current values.
device_id=list - returns values of specified devices (e.g. "1234,5678")
channel_id=list - returns values of specified channels (e.g. "1234,5678")
datapoint_id=list - returns Value() for datapoint with id (e.g. "1234,5678")
statechange.cgi             Allows to change the state of one or more devices.
ise_id=list - selects the devices with the specified ids (e.g. "1234,5678")
new_value=list - new values for device states (e.g. "0.20,1.45")
statelist.cgi               Outputs all devices with channels and their current values.
ise_id=int - output only channels and values of device with specified id (e.g. "1234")
show_internal=0/1 - adds internal channels also (default=0)
show_remote=0/1 - adds output of virtual remote channels (default=0)
systemNotification.cgi     Outputs the currently existing system notifications.
systemNotificationClear.cgi Clears the current active system notifications (if not sticky).
sysvar.cgi                 Outputs a single system variable with its corresponding values.
ise_id=int - the id of the system variable to output (e.g. "1234")
text=true/false - outputs or suppressed the text for string variables (default=true)
sysvarlist.cgi             Outputs all system variables with their corresponding values.
text=true/false - outputs or suppressed the text for string variables (default=false)
tokenlist.cgi Lists all registered security access tokens.
tokenregister.cgi Registers a new security access token.
desc=string - description for new token id
tokenrevoke.cgi Revokes an existing security access token.
sid=string - security access token id
update.cgi ????
checkupdate=list - ???
maxdurchlaeufe=int - ??? (default=7)
version.cgi Outputs version of XML-API.

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.

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.

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:

https://<CCU-IP>/addons/xmlapi/statechange.cgi?sid=[TOKEN_ID]&ise_id=12345&new_value=0.20

This call, if executed with a registered [TOKEN_ID] and the right ise_id and IP address would then e.g. set a dimmer to 20%.

Support

https://homematic-forum.de/forum/viewtopic.php?f=26&t=10098&p=75959#p75959

Authors

  • jens-maus, Maik (Monty1979), Philipp (ultrah), hobbyquaker, dirch, Uwe (uwe111)

About

HomeMatic CCU Addon implementing a xml request functionality

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Tcl 98.6%
  • Shell 1.4%