# xcom-protocol
Python library implementing Studer-Innotec Xcom protocol for Xcom-232i and Xcom-LAN (TCP/UDP).
NOTE: This lib is still WiP, so functionality is still limited, but feel free to create a [pull request](https://github.com/zocker-160/xcom-protocol/pulls) if you want to contribute ;)
DISCLAIMER: This library is NOT officially made by Studer-Innotec.
The complete official documentation is available on: \
[Studer-Innotec Download Center](https://www.studer-innotec.com/en/downloads/) *-> Software and Updates -> Communication protocol Xcom-232i*
## Getting Started
### Requirements
#### Hardware
- Xcom-232i or Xcom-LAN connected to your installation
- Xcom-232i connected to PC using USB to RS-232 adapter (1) or PC in same local network as Xcom-LAN device
- PC with at least USB2.0 or faster (works on Raspberry Pi 3/4 as well)
(1) I personally am successfully using an adapter with the PL2303 chipset like [this one](https://www.amazon.de/dp/B00QUZY4UG)
#### Software
- any Linux based OS (x86 / ARM)
- python3 >= 3.9
- python3-pip
### Installation
```bash
pip install xcom-proto
```
#### Important
- make sure you select the USB to RS-232 adapter as the `serialDevice`, usually on Linux it is `/dev/ttyUSB[0-9]`
- when using Xcom-LAN UDP make sure MOXA is set up properly and reachable via a static IP in the local network
- when using Xcom-LAN TCP make sure your device IP is static, reachable in the local network and specified in the MOXA
### MOXA Setup for Xcom-LAN TCP
- address to Studer Portal is optional and can be removed if you don't need their web interface
- `Data Packing` has to be set exactly as shown, you will get `AssertionError` otherwise
#### Important
If you want Studer Portal to still keep working, make sure you wait for at least 5 - 10 seconds to give it time to send data.
### Adressing Devices
Make sure you are setting the correct destination Address `dstAddr` otherwise read / write operations might not work.
By default `getValue` and `setValue` use the address `100`, which is a multicast address for all XTH, XTM and XTS devices, it does NOT include VarioTrack, VarioString or BSP.
Furthermore if you have more than one device of each type (VarioString, VarioTrack, XTS etc.) then using the multicast address is probably not desired either.
**NOTE:** for code examples see below
All used addresses of Studer devices can be found in the Studer documentation (page 8, section 3.5):
## Examples
### Reading values
```python
from xcom_proto import XcomP as param
from xcom_proto import XcomC
from xcom_proto import XcomRS232
from xcom_proto import XcomLANUDP
xcom = XcomRS232(serialDevice="/dev/ttyUSB0", baudrate=115200)
# OR (default ports are 4002 and 4001)
xcom = XcomLANUDP("192.168.178.110")
# OR overwriting ports
xcom = XcomLANUDP("192.168.178.110", dstPort=4002, srcPort=4001)
boostValue = xcom.getValue(param.SMART_BOOST_LIMIT)
pvmode = xcom.getValue(param.PV_OPERATION_MODE)
pvpower = xcom.getValue(param.PV_POWER) * 1000 # convert from kW to W
sunhours = xcom.getValue(param.PV_SUN_HOURS_CURR_DAY)
energyProd = xcom.getValue(param.PV_ENERGY_CURR_DAY)
soc = xcom.getValue(param.BATT_SOC)
battPhase = xcom.getValue(param.BATT_CYCLE_PHASE)
battCurr = xcom.getValue(param.BATT_CURRENT)
battVolt = xcom.getValue(param.BATT_VOLTAGE)
# please look into the official Studer parameter documentation to find out
# what type a parameter has
pvmode_manual = xcom.getValueByID(11016, XcomC.TYPE_SHORT_ENUM)
# using custom dstAddr (can also be used for getValueByID())
solarPowerVS1 = xcom.getValue(param.VS_PV_POWER, dstAddr=701)
solarPowerVS2 = xcom.getValue(param.VS_PV_POWER, dstAddr=702)
print(boostValue, pvmode, pvpower, sunhours, energyProd, soc, battPhase, battCurr, battVolt)
```
#### XcomLAN TCP
```python
from xcom_proto import XcomP as param
from xcom_proto import XcomC
from xcom_proto import XcomRS232
from xcom_proto import XcomLANTCP
with XcomLANTCP(port=4001) as xcom:
boostValue = xcom.getValue(param.SMART_BOOST_LIMIT)
# same as above
```
### Writing values
**IMPORTANT**:
`setValue()` and `setValueByID()` have an optional named parameter `propertyID` which you can pass either:
- `XcomC.QSP_UNSAVED_VALUE`: writes value into RAM only (default when not specified)
- `XcomC.QSP_VALUE`: writes value into flash memory; **you should write into flash only if you *really* need it, write cycles are limited!**
```python
from xcom_proto import XcomP as param
from xcom_proto import XcomC
from xcom_proto import XcomRS232
from xcom_proto import XcomLANUDP
xcom = XcomRS232(serialDevice="/dev/ttyUSB0", baudrate=115200)
# OR (default ports are 4002 and 4001)
xcom = XcomLANUDP("192.168.178.110")
# OR overwriting ports
xcom = XcomLANUDP("192.168.178.110", dstPort=4002, srcPort=4001)
xcom.setValue(param.SMART_BOOST_LIMIT, 100) # writes into RAM
xcom.setValue(param.FORCE_NEW_CYCLE, 1, propertyID=XcomC.QSP_VALUE) # writes into flash memory
# using custom dstAddr
xcom.setValue(param.BATTERY_CHARGE_CURR, 2, dstAddr=101) # writes into RAM
xcom.setValue(param.BATTERY_CHARGE_CURR, 2, dstAddr=101, propertyID=XcomC.QSP_VALUE) # writes into flash memory
# using custom value by ID
xcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30) # writes into RAM
xcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30, propertyID=XcomC.QSP_VALUE) # writes into flash memory
# using custom value by ID and dstAddr
xcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30, dstAddr=101) # writes into RAM
xcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30, dstAddr=101, propertyID=XcomC.QSP_VALUE) # writes into flash memory
```
#### XcomLAN TCP
```python
from xcom_proto import XcomP as param
from xcom_proto import XcomC
from xcom_proto import XcomRS232
from xcom_proto import XcomLANTCP
with XcomLANTCP(port=4001) as xcom:
xcom.setValue(param.SMART_BOOST_LIMIT, 100) # writes into RAM
xcom.setValue(param.FORCE_NEW_CYCLE, 1, propertyID=XcomC.QSP_VALUE) # writes into flash memory
# same as above
```
## Troubleshooting
### Writing value returns `Permission Denied` error
Usually this is caused by using the default multicast address to write values that are not part of the default address range. See [above](#adressing-devices) for more information.
### `AssertionError` (invalid header / frame)
Usually this is caused by a wrong MOXA setup when using UDP / TCP, make sure `Data Packing` is set correctly in the MOXA. See [above](#moxa-setup-for-xcom-lan-tcp) for more information.
When using Xcom-232i then checksum errors and AssertionErrors can be caused by a bad RS232 connection or a wrong BAUD rate setting.
Raw data
{
"_id": null,
"home_page": "https://github.com/zocker-160/xcom-protocol",
"name": "xcom-proto",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "zocker_160",
"author_email": "zocker1600@posteo.net",
"download_url": "https://files.pythonhosted.org/packages/c8/e6/670ec99cd8b4570dedd5b61dde635db7b80b6166d94086dd382c39ce7c8e/xcom_proto-0.3.6.tar.gz",
"platform": null,
"description": "# xcom-protocol\n\nPython library implementing Studer-Innotec Xcom protocol for Xcom-232i and Xcom-LAN (TCP/UDP).\n\nNOTE: This lib is still WiP, so functionality is still limited, but feel free to create a [pull request](https://github.com/zocker-160/xcom-protocol/pulls) if you want to contribute ;)\n\nDISCLAIMER: This library is NOT officially made by Studer-Innotec.\n\nThe complete official documentation is available on: \\\n[Studer-Innotec Download Center](https://www.studer-innotec.com/en/downloads/) *-> Software and Updates -> Communication protocol Xcom-232i*\n\n## Getting Started\n\n### Requirements\n#### Hardware\n\n- Xcom-232i or Xcom-LAN connected to your installation\n- Xcom-232i connected to PC using USB to RS-232 adapter (1) or PC in same local network as Xcom-LAN device\n- PC with at least USB2.0 or faster (works on Raspberry Pi 3/4 as well)\n\n(1) I personally am successfully using an adapter with the PL2303 chipset like [this one](https://www.amazon.de/dp/B00QUZY4UG)\n\n#### Software\n\n- any Linux based OS (x86 / ARM)\n- python3 >= 3.9\n- python3-pip\n\n### Installation\n\n```bash\npip install xcom-proto\n```\n#### Important\n\n- make sure you select the USB to RS-232 adapter as the `serialDevice`, usually on Linux it is `/dev/ttyUSB[0-9]`\n- when using Xcom-LAN UDP make sure MOXA is set up properly and reachable via a static IP in the local network\n- when using Xcom-LAN TCP make sure your device IP is static, reachable in the local network and specified in the MOXA\n\n### MOXA Setup for Xcom-LAN TCP\n\n\n- address to Studer Portal is optional and can be removed if you don't need their web interface\n- `Data Packing` has to be set exactly as shown, you will get `AssertionError` otherwise\n\n#### Important\nIf you want Studer Portal to still keep working, make sure you wait for at least 5 - 10 seconds to give it time to send data.\n\n### Adressing Devices\n\nMake sure you are setting the correct destination Address `dstAddr` otherwise read / write operations might not work.\n\nBy default `getValue` and `setValue` use the address `100`, which is a multicast address for all XTH, XTM and XTS devices, it does NOT include VarioTrack, VarioString or BSP.\n\nFurthermore if you have more than one device of each type (VarioString, VarioTrack, XTS etc.) then using the multicast address is probably not desired either.\n\n**NOTE:** for code examples see below\n\nAll used addresses of Studer devices can be found in the Studer documentation (page 8, section 3.5):\n\n\n## Examples\n### Reading values\n\n```python\nfrom xcom_proto import XcomP as param\nfrom xcom_proto import XcomC\nfrom xcom_proto import XcomRS232\nfrom xcom_proto import XcomLANUDP\n\nxcom = XcomRS232(serialDevice=\"/dev/ttyUSB0\", baudrate=115200)\n# OR (default ports are 4002 and 4001)\nxcom = XcomLANUDP(\"192.168.178.110\")\n# OR overwriting ports\nxcom = XcomLANUDP(\"192.168.178.110\", dstPort=4002, srcPort=4001)\n\nboostValue = xcom.getValue(param.SMART_BOOST_LIMIT)\n\npvmode = xcom.getValue(param.PV_OPERATION_MODE)\npvpower = xcom.getValue(param.PV_POWER) * 1000 # convert from kW to W\nsunhours = xcom.getValue(param.PV_SUN_HOURS_CURR_DAY)\nenergyProd = xcom.getValue(param.PV_ENERGY_CURR_DAY)\n\nsoc = xcom.getValue(param.BATT_SOC)\nbattPhase = xcom.getValue(param.BATT_CYCLE_PHASE)\nbattCurr = xcom.getValue(param.BATT_CURRENT)\nbattVolt = xcom.getValue(param.BATT_VOLTAGE)\n\n# please look into the official Studer parameter documentation to find out\n# what type a parameter has\npvmode_manual = xcom.getValueByID(11016, XcomC.TYPE_SHORT_ENUM)\n\n# using custom dstAddr (can also be used for getValueByID())\nsolarPowerVS1 = xcom.getValue(param.VS_PV_POWER, dstAddr=701)\nsolarPowerVS2 = xcom.getValue(param.VS_PV_POWER, dstAddr=702)\n\nprint(boostValue, pvmode, pvpower, sunhours, energyProd, soc, battPhase, battCurr, battVolt)\n```\n\n#### XcomLAN TCP\n\n```python\nfrom xcom_proto import XcomP as param\nfrom xcom_proto import XcomC\nfrom xcom_proto import XcomRS232\nfrom xcom_proto import XcomLANTCP\n\nwith XcomLANTCP(port=4001) as xcom:\n boostValue = xcom.getValue(param.SMART_BOOST_LIMIT)\n # same as above\n```\n\n### Writing values\n\n**IMPORTANT**:\n`setValue()` and `setValueByID()` have an optional named parameter `propertyID` which you can pass either:\n\n- `XcomC.QSP_UNSAVED_VALUE`: writes value into RAM only (default when not specified)\n- `XcomC.QSP_VALUE`: writes value into flash memory; **you should write into flash only if you *really* need it, write cycles are limited!**\n\n```python\nfrom xcom_proto import XcomP as param\nfrom xcom_proto import XcomC\nfrom xcom_proto import XcomRS232\nfrom xcom_proto import XcomLANUDP\n\nxcom = XcomRS232(serialDevice=\"/dev/ttyUSB0\", baudrate=115200)\n# OR (default ports are 4002 and 4001)\nxcom = XcomLANUDP(\"192.168.178.110\")\n# OR overwriting ports\nxcom = XcomLANUDP(\"192.168.178.110\", dstPort=4002, srcPort=4001)\n\nxcom.setValue(param.SMART_BOOST_LIMIT, 100) # writes into RAM\nxcom.setValue(param.FORCE_NEW_CYCLE, 1, propertyID=XcomC.QSP_VALUE) # writes into flash memory\n\n# using custom dstAddr\nxcom.setValue(param.BATTERY_CHARGE_CURR, 2, dstAddr=101) # writes into RAM\nxcom.setValue(param.BATTERY_CHARGE_CURR, 2, dstAddr=101, propertyID=XcomC.QSP_VALUE) # writes into flash memory\n\n# using custom value by ID\nxcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30) # writes into RAM\nxcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30, propertyID=XcomC.QSP_VALUE) # writes into flash memory\n\n# using custom value by ID and dstAddr\nxcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30, dstAddr=101) # writes into RAM\nxcom.setValueByID(1107, XcomC.TYPE_FLOAT, 30, dstAddr=101, propertyID=XcomC.QSP_VALUE) # writes into flash memory\n```\n\n#### XcomLAN TCP\n\n```python\nfrom xcom_proto import XcomP as param\nfrom xcom_proto import XcomC\nfrom xcom_proto import XcomRS232\nfrom xcom_proto import XcomLANTCP\n\nwith XcomLANTCP(port=4001) as xcom:\n xcom.setValue(param.SMART_BOOST_LIMIT, 100) # writes into RAM\n xcom.setValue(param.FORCE_NEW_CYCLE, 1, propertyID=XcomC.QSP_VALUE) # writes into flash memory\n # same as above\n```\n\n## Troubleshooting\n### Writing value returns `Permission Denied` error\n\nUsually this is caused by using the default multicast address to write values that are not part of the default address range. See [above](#adressing-devices) for more information.\n\n### `AssertionError` (invalid header / frame)\n\nUsually this is caused by a wrong MOXA setup when using UDP / TCP, make sure `Data Packing` is set correctly in the MOXA. See [above](#moxa-setup-for-xcom-lan-tcp) for more information.\n\nWhen using Xcom-232i then checksum errors and AssertionErrors can be caused by a bad RS232 connection or a wrong BAUD rate setting.\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Python library implementing Studer-Innotec Xcom protocol used by Xcom-232i and Xcom-LAN",
"version": "0.3.6",
"project_urls": {
"Homepage": "https://github.com/zocker-160/xcom-protocol",
"Repository": "https://github.com/zocker-160/xcom-protocol"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6a4547a3d0a5abf3eeae418b7493fd03faa2567bf10a788ee762a33e59d64293",
"md5": "89a6184f3d4aa2c0f817622d2bc95059",
"sha256": "5ec029ea5972c90b6a9a77a7bdfb768079fa7bc3a4e85b0ae4411040a8b7600c"
},
"downloads": -1,
"filename": "xcom_proto-0.3.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "89a6184f3d4aa2c0f817622d2bc95059",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 23508,
"upload_time": "2024-05-04T16:46:12",
"upload_time_iso_8601": "2024-05-04T16:46:12.797969Z",
"url": "https://files.pythonhosted.org/packages/6a/45/47a3d0a5abf3eeae418b7493fd03faa2567bf10a788ee762a33e59d64293/xcom_proto-0.3.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c8e6670ec99cd8b4570dedd5b61dde635db7b80b6166d94086dd382c39ce7c8e",
"md5": "78415ba77057cb60e65665dd53660f89",
"sha256": "960e4bd2aa0c4c42ad67d077e1a5ac85348c393099032b5ffd7890dd2f441d2a"
},
"downloads": -1,
"filename": "xcom_proto-0.3.6.tar.gz",
"has_sig": false,
"md5_digest": "78415ba77057cb60e65665dd53660f89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 23606,
"upload_time": "2024-05-04T16:46:14",
"upload_time_iso_8601": "2024-05-04T16:46:14.665588Z",
"url": "https://files.pythonhosted.org/packages/c8/e6/670ec99cd8b4570dedd5b61dde635db7b80b6166d94086dd382c39ce7c8e/xcom_proto-0.3.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-04 16:46:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zocker-160",
"github_project": "xcom-protocol",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "xcom-proto"
}
JSON
