{"id":13604789,"url":"https://github.com/homematic-community/XML-API","last_synced_at":"2025-04-12T02:31:34.488Z","repository":{"id":4996378,"uuid":"6154561","full_name":"homematic-community/XML-API","owner":"homematic-community","description":"HomeMatic CCU Addon implementing a xml request functionality","archived":false,"fork":false,"pushed_at":"2024-03-14T23:43:50.000Z","size":1117,"stargazers_count":122,"open_issues_count":11,"forks_count":27,"subscribers_count":33,"default_branch":"master","last_synced_at":"2024-05-22T01:14:39.355Z","etag":null,"topics":["ccu","homematic","raspberrymatic","smarthome"],"latest_commit_sha":null,"homepage":"https://github.com/homematic-community/XML-API","language":"Tcl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"dain/snappy","license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/homematic-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-10-10T08:53:11.000Z","updated_at":"2024-06-11T01:55:45.951Z","dependencies_parsed_at":"2023-11-13T13:25:59.006Z","dependency_job_id":"930820d2-8836-4766-abfb-69e66d1e6b2a","html_url":"https://github.com/homematic-community/XML-API","commit_stats":{"total_commits":215,"total_committers":9,"mean_commits":23.88888888888889,"dds":0.5906976744186047,"last_synced_commit":"a701c5763d55094e6e8b205d23efa1c0c080b8b6"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homematic-community%2FXML-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homematic-community%2FXML-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homematic-community%2FXML-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homematic-community%2FXML-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/homematic-community","download_url":"https://codeload.github.com/homematic-community/XML-API/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223489642,"owners_count":17153793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ccu","homematic","raspberrymatic","smarthome"],"created_at":"2024-08-01T19:00:51.282Z","updated_at":"2024-11-07T09:30:53.195Z","avatar_url":"https://github.com/homematic-community.png","language":"Tcl","funding_links":[],"categories":["CCU Addons"],"sub_categories":[],"readme":"# XML-API CCU Addon\n\n[![Release](https://img.shields.io/github/release/homematic-community/XML-API.svg)](https://github.com/homematic-community/XML-API/releases/latest)\n[![Downloads](https://img.shields.io/github/downloads/homematic-community/XML-API/latest/total.svg)](https://github.com/homematic-community/XML-API/releases/latest)\n[![Issues](https://img.shields.io/github/issues/homematic-community/XML-API.svg)](https://github.com/homematic-community/XML-API/issues)\n[![License](https://img.shields.io/badge/license-GPL%203.0-green.svg)](https://opensource.org/licenses/GPL-3.0)\n\nA 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.\n\n## Supported CCU models\n* [HomeMatic CCU3](https://www.eq-3.de/produkte/homematic/zentralen-und-gateways/smart-home-zentrale-ccu3.html) / [RaspberryMatic](https://raspberrymatic.de/)\n* [HomeMatic CCU2](https://www.eq-3.de/produkt-detail-zentralen-und-gateways/items/homematic-zentrale-ccu-2.html)\n* HomeMatic CCU1\n\n## Installation\nThis 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.\n\n## Use\nAfter installation the XML-API should be avilable via the following URL call:\n```\nhttps://[CCU_IP]/addons/xmlapi/[ScriptName]?sid=[TOKEN_ID]\n```\nwhere [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:\n\n| ScriptName                    | Description / Parameters  \n| ----------------------------- |-------------------------\n| `checkuptodate.cgi`           | ???\n| `devicelist.cgi`              | Lists all devices with channels. Contain names, serial number, device type and ids.\u003cbr\u003e`device_id=list` - returns values of specified devices (e.g. \"1234,5678\") (optional)\u003cbr\u003e`show_internal=0/1` - adds internal channels also (default=0)\u003cbr\u003e`show_remote=0/1` - adds output of virtual remote channels (default=0)\n| `devicetypelist.cgi`          | Lists all possible device types with their possible meta data.\n| `exec.cgi`                    | Allows to execute arbitrary ReGaHss script commands (as POST data).\n| `favoritelist.cgi`            | Lists all favorites and users.\u003cbr\u003e`show_datapoint=0/1` - outputs datapoint_id and datapoint_type also (default=0)\u003cbr\u003e`show_internal=0/1` - adds internal channels also (default=0)\n| `functionlist.cgi`            | Lists all functions including channels.\n| `mastervalue.cgi`             | Outputs a single or several '1234,5678' devices with their names and master values.\u003cbr\u003e`device_id=list` - returns master values of specified devices (e.g. \"1234,5678\")\u003cbr\u003e`requested_names=list` - returns only master values of selected types (e.g. \"TEMPERATURE_COMFORT,TEMPERATURE_LOWERING\")\n| `mastervaluechange.cgi`       | Sets one or more master values for a list of devices.\u003cbr\u003e`device_id=list` - sets master values of specified devices (e.g. \"1234,5678\")\u003cbr\u003e`name=list` - sets only master values of selected types (e.g. \"TEMPERATURE_LOWERING,TEMPERATURE_COMFORT\")\u003cbr\u003e`value=list` - sets master values to specified values (e.g. \"17.0,22.5\")\n| `programactions.cgi`          | Allows to change active and visible program options.\u003cbr\u003e`program_id=int` - id of program to modify (e.g. \"1234\")\u003cbr\u003e`active=true/false` - sets active status of program to true/false\u003cbr\u003e`visible=true/false` - sets visible status of program to true/false\n| `programlist.cgi`             | Lists all programs.\n| `protocol.cgi`                | Outputs the system protocol.\u003cbr\u003e`start=int` - start of the protocol\u003cbr\u003e`show=int` - number of entries to output\u003cbr\u003e`clear=0/1` - allows to clear the system protocol\n| `roomlist.cgi`                | Lists all configured rooms including channels.\n| `rssilist.cgi`                | Lists RSSI values of all RF devices.\n| `runprogram.cgi`              | Starts a program with the specified id.\u003cbr\u003e`program_id=int` - id of program to modify (e.g. \"1234\")\u003cbr\u003e`cond_check=0/1` - execute program with normal condition checks or not (only first \"then\" is executed) (default=0)\n| `scripterrors.cgi`            | Searches for the last 10 lines in `/var/log/messages` containing script runtime errors and outputs them.\n| `state.cgi`                   | Outputs one or more devices with their channels and current values.\u003cbr\u003e`device_id=list` - returns values of specified devices (e.g. \"1234,5678\")\u003cbr\u003e`channel_id=list` - returns values of specified channels (e.g. \"1234,5678\")\u003cbr\u003e`datapoint_id=list` - returns Value() for datapoint with id (e.g. \"1234,5678\")\n| `statechange.cgi`             | Allows to change the state of one or more devices.\u003cbr\u003e`ise_id=list` - selects the devices with the specified ids (e.g. \"1234,5678\")\u003cbr\u003e`new_value=list` - new values for device states (e.g. \"0.20,1.45\")\n| `statelist.cgi`               | Outputs all devices with channels and their current values.\u003cbr\u003e`ise_id=int` - output only channels and values of device with specified id (e.g. \"1234\")\u003cbr\u003e`show_internal=0/1` - adds internal channels also (default=0)\u003cbr\u003e`show_remote=0/1` - adds output of virtual remote channels (default=0)\n| `systemNotification.cgi`      | Outputs the currently existing system notifications.\n| `systemNotificationClear.cgi` | Clears the current active system notifications (if not sticky).\n| `sysvar.cgi`                  | Outputs a single system variable with its corresponding values.\u003cbr\u003e`ise_id=int` - the id of the system variable to output (e.g. \"1234\")\u003cbr\u003e`text=true/false` - outputs or suppressed the text for string variables (default=true)\n| `sysvarlist.cgi`              | Outputs all system variables with their corresponding values.\u003cbr\u003e`text=true/false` - outputs or suppressed the text for string variables (default=false)\n| `tokenlist.cgi`               | Lists all registered security access tokens.\n| `tokenregister.cgi`           | Registers a new security access token.\u003cbr\u003e`desc=string` - description for new token id\n| `tokenrevoke.cgi`             | Revokes an existing security access token.\u003cbr\u003e`sid=string` - security access token id\n| `update.cgi`                  | ????\u003cbr\u003e`checkupdate=list` - ???\u003cbr\u003e`maxdurchlaeufe=int` - ??? (default=7)\n| `version.cgi`                 | Outputs version of XML-API.\n\nAll 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 -\u003e Control panel -\u003e Additional software -\u003e XML-API -\u003e 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.\n\nIf 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. \n\nIn 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:\n```\nhttps://\u003cCCU-IP\u003e/addons/xmlapi/statechange.cgi?sid=[TOKEN_ID]\u0026ise_id=12345\u0026new_value=0.20\n```\nThis 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%.\n\n## Support\nhttps://homematic-forum.de/forum/viewtopic.php?f=26\u0026t=10098\u0026p=75959#p75959\n\n## Authors\n* jens-maus, Maik (Monty1979), Philipp (ultrah), hobbyquaker, dirch, Uwe (uwe111)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomematic-community%2FXML-API","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhomematic-community%2FXML-API","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomematic-community%2FXML-API/lists"}