{"id":16791901,"url":"https://github.com/ankohanse/aioxcom","last_synced_at":"2025-04-10T23:51:16.994Z","repository":{"id":255440501,"uuid":"850192927","full_name":"ankohanse/aioxcom","owner":"ankohanse","description":"Async python library to communicate with Studer-Innotec devices via Xcom protocol","archived":false,"fork":false,"pushed_at":"2025-04-06T02:45:12.000Z","size":2433,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T03:26:00.967Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ankohanse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"ankohanse","thanks_dev":null,"custom":null}},"created_at":"2024-08-31T05:27:02.000Z","updated_at":"2025-04-06T02:45:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"a0ebb94a-9ee0-4fab-898b-05bf37c8db33","html_url":"https://github.com/ankohanse/aioxcom","commit_stats":null,"previous_names":["ankohanse/aioxcom"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankohanse%2Faioxcom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankohanse%2Faioxcom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankohanse%2Faioxcom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankohanse%2Faioxcom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ankohanse","download_url":"https://codeload.github.com/ankohanse/aioxcom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248317707,"owners_count":21083528,"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":[],"created_at":"2024-10-13T08:43:26.353Z","updated_at":"2025-04-10T23:51:16.975Z","avatar_url":"https://github.com/ankohanse.png","language":"Python","funding_links":["https://buymeacoffee.com/ankohanse","https://www.buymeacoffee.com/ankohanse"],"categories":[],"sub_categories":[],"readme":"[![license](https://img.shields.io/github/license/toreamun/amshan-homeassistant?style=for-the-badge)](LICENSE)\n[![buy_me_a_coffee](https://img.shields.io/badge/If%20you%20like%20it-Buy%20me%20a%20coffee-yellow.svg?style=for-the-badge)](https://www.buymeacoffee.com/ankohanse)\n\n\n# aioxcom\n\nPython library for retrieving sensor information from Studer-Innotec devices.\nThis component connects directly over the local network using the Studer xcom protocol.\n\nThe custom component is comfirmed to be compatible with:\n- Xtender XTH 8000-48, XTM 4000\n- Xcom-CAN (BSP connection to a third party BMS)\n- Xcom-LAN (which actually is a Xcom232i with a Moxy NPort 5110A)\n- BMS\n- RCC-03\n- VarioTrack\n\nIt should also be able to detect and handle\n- Xtender (any other XTH, XTS and XTM models)\n- VarioString\n- RCC-02\n\nDisclaimer: this library is NOT created by Studer-Innotec, but is based on their documentation of the Xcom protocol.\nThat documentation can be found on:\n[Studer-Innotec Download Center](https://www.studer-innotec.com/en/downloads/) *-\u003e Software and Updates -\u003e Communication protocol Xcom-232i*\n\n\n# Prerequisites\n\nThis device depends on having a Studer Xcom-LAN (i.e. an Xcom-232i and a Moxa ethernet gateway) acting as a Xcom client and connecting to this integration. For older systems this will be a separate component, for future systems Studer have indicated that LAN connection will become part of the Xtender range.\n\nThe Studer Xcom-LAN will be able to simultaneously send data to the Studer online portal as well as sending data to this integration.\n\nConfiguration steps:\n\n1. Download and install the Moxa DSU tool (Device Search Utility)\n    - Open [www.moxa.com](https://www.moxa.com) in a browser\n    - Select Support -\u003e Software and Documentation\n    - Choose NPort 5100A series (or whatever specific device you have)\n    - Scroll down under 'Related Software, Firmware and Drivers' to find 'Device Search Utility'\n    - Download and install the utility\n\n2. Locate the Moxa NPort device on the local network\n    - Run the Moxa Device Search Utility\n    - Press the 'Search' button and wait until the search finishes\n    - The utility should display the found NPort device\n    - Double click on the found device to open its configuration page\n\n      ![dsu_search_results](documentation/DSU_results.png)\n\n3. Configure the Moxa NPort device\n    - In the Main Menu, select 'Operating Settings' -\u003e Port 1\n    - Verify that 'Operation Mode' is set to 'TCP Client'\n    - Add the ip-address of your HomeAssistant as 'Destination IP address'\n    - Set Delimeter 1 to '0d' and Enable\n    - Set Delimeter 2 to '0a' and Enable\n    - Set Delimeter Process to 'Strip Delimeter'\n    - Press the 'Submit' button\n    - Press 'Save/Restart'\n\n      ![moxa_operating_settings](documentation/Moxa_operating_settings.png)\n\n\n# Usage\n\nThe library is available from PyPi using:\n`pip install aioxcom`\n\nTo read an infos or param or write to a param:\n\n```\nfrom aioxcom import XcomApiTcp, XcomDataset, VOLTAGE\n\ndataset = await XcomDataset.create(VOLTAGE.AC240) # or use VOLTAGE.AC120\ninfo_3023 = dataset.getByNr(3023, \"xt\")  # the \"xt\" part is optional but usefull for detecting mistakes\ninfo_6001 = dataset.getByNr(6001, \"bsp\")\nparam_1107 = dataset.getByNr(1107, \"xt\")\ndataset = None  # Release memory of the dataset\n\napi = XcomApiTcp(4001)    # port number configured in Xcom-LAN/Moxa NPort\ntry:\n    if not await api.start():\n        logger.info(f\"Did not connect to Xcom\")\n        return\n\n    # Retrieve info #3023 from the first Xtender (Output power)\n    value = await api.requestValue(info_3023, \"XT1\")    # xt address range is 101 to 109, or use \"XT1\" to \"XT9\"\n    logger.info(f\"XT1 3023: {value} {info_3023.unit} ({info_3023.name})\")\n\n    # Retrieve param #6001 from BSP (Nominal capacity)\n    value = await api.requestValue(info_6001, \"BSP\")    # bsp address range is only 601, or use \"BSP\"\n    logger.info(f\"BSP 6001: {value} {info_6001.unit} ({info_6001.name})\")\n\n    # Update param 1107 on the first Xtender (Maximum current of AC source)\n    value = 4.0    # 4 Ampere\n    if await api.updateValue(param_1107, value, \"XT1\"):\n        logger.info(f\"XT1 1107 updated to {value} {param_1107.unit} ({param_1107.name})\")\n\nfinally:\n    await api.stop()\n```\n\nA complete list of param and infos numbers can be found in the source of this library in file `src/aioxcom/xcom_datapoints_240v.json`  \n\nA complete list of all available device families and their address range can be found in file `src/aioxcom/xcom_families.py`  \n\n\n# Param writes to device RAM\n\nWhen the value of a Studer param is changed via this library, these are written via Xcom to the affected device. \nChanges are stored in the device's RAM memory, not in its flash memory as you can only write to flash a limited number of times over its lifetime.\n\nHowever, reading back the value from the entity will always be from flash. As a result, the change to the entity value is not visible in the RCC or remote console. You can only tell from the behavior of the PV system that the Studer param was indeed changed.  \n  \nAfter a restart/reboot of the PV system the system will revert to the value from Flash. So you may want to periodically repeat the write of changed param values via an automation.\n\n**IMPORTANT**:\n\nBe very carefull in changing params marked as having level Expert, Installer or even Qualified Service Person. If you do not know what the effect of a Studer param change is, then do not change it.\n\n\n# Credits\n\nSpecial thanks to the following people for providing the information this library is based on:\n- [zocker-160](https://github.com/zocker-160/xcom-protocol)\n- [Michael Jeffers](https://community.home-assistant.io/u/JeffersM)\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankohanse%2Faioxcom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fankohanse%2Faioxcom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankohanse%2Faioxcom/lists"}